Understanding the Rails Authenticity Token in Ruby on Rails

By the end of this page, you will understand what the Rails authenticity token is, how it helps prevent CSRF attacks, where it appears in forms and requests, and how developers work with it in everyday Rails applications.

The authenticity token in Rails is a security value used to help protect your application from Cross-Site Request Forgery (CSRF) attacks.

A CSRF attack happens when a user is logged into your Rails app, and a malicious site tricks their browser into sending a request to your app without the user's intent. Because the browser may automatically include session cookies, your app could mistakenly treat that request as legitimate.

Rails defends against this by adding a unique token to forms and checking that token when the form is submitted. If the token is missing or invalid, Rails can reject the request.

Why this matters

Without CSRF protection, dangerous actions could be triggered silently, such as:

• changing an email address
• updating account settings
• deleting data
• submitting payments
• creating or modifying records

How Rails uses it

When CSRF protection is enabled, Rails:

• generates an authenticity token for the user's session
• embeds it in non-GET forms
• verifies the token on incoming state-changing requests such as POST, PATCH, PUT, and DELETE
• rejects requests that fail verification

In Rails controllers, this is typically handled automatically through built-in CSRF protection.

class ApplicationController < ActionController::Base
  protect_from_forgery with: :exception
end

This tells Rails to raise an exception if a request fails CSRF verification.

Important idea

The authenticity token is not for user authentication like a password or login token. It is specifically for proving that a form submission came from a page your Rails app generated for that user.

Think of the authenticity token like a secret stamp that your app places on every official form.

• Your Rails app creates the form.
• It adds a hidden security stamp.
• When the form comes back, Rails checks for that stamp.
• If the stamp is missing or wrong, Rails assumes the request may be forged.

A malicious website can try to send a request to your app, but it usually cannot read and reuse the correct secret stamp from your Rails page. That is what makes the token useful.

So the mental model is:

• session cookie = identifies the logged-in user
• authenticity token = proves the request came from a trusted Rails-generated form

You usually need both for a safe state-changing request.

Rails usually adds the authenticity token automatically in forms created with Rails helpers.

Example: form_with

<%= form_with model: @post do |form| %>
  <%= form.text_field :title %>
  <%= form.submit "Save" %>
<% end %>

Rails generates HTML that includes a hidden field similar to this:

<input type="hidden" name="authenticity_token" value="...token here...">

Example: form_tag

<%= form_tag posts_path do %>
  <%= text_field_tag :title %>
  <%= submit_tag "Create Post" %>
<% end %>

This also includes an authenticity token automatically.

Example: token in page markup for JavaScript

Rails often includes a CSRF token in a meta tag so JavaScript-based requests can send it too:

<%= csrf_meta_tags %>

This renders tags like:

<meta name="csrf-param" content=>

Consider this Rails form:

<%= form_with url: posts_path, method: :post do |form| %>
  <%= form.text_field :title %>
  <%= form.submit "Create" %>
<% end %>

Here is what happens step by step:

1. A user visits the page.
2. Rails renders the form on the server.
3. Rails inserts a hidden authenticity_token field into the HTML.
4. The browser displays the form to the user.
5. The user enters a title and clicks Create.
6. The browser submits the form data, including the hidden token.
7. Rails receives the request and checks the token.
8. If the token matches what Rails expects for that session, the request continues.
9. If the token is missing or invalid, Rails rejects the request.

Simplified submitted form data

title=My+Post
authenticity_token=abc123...

If the token is valid

The controller action runs normally:

class PostsController < ApplicationController
  def create
    @post = Post.create!(title: params[:title])
    redirect_to @post
  end
end

If the token is invalid

Authenticity tokens are used any time a Rails app accepts requests that change data.

Common examples

• Login and logout forms

  • Prevent forged requests that sign users out or attempt unwanted actions.

• Account settings forms

  • Protect updates to email, password, profile, or notification settings.

• Admin dashboards

  • Prevent attackers from tricking an admin into deleting users or changing permissions.

• Shopping carts and checkout flows

  • Protect quantity changes, address updates, and order submission.

• AJAX requests in single-page features

  • JavaScript requests that create, update, or delete data usually send the CSRF token in a header.

• Buttons using DELETE or PATCH

  • Rails links and buttons that act like non-GET requests rely on CSRF protection too.

In short, if a request changes application state, CSRF protection is relevant.

In real Rails codebases, developers usually do not manually manage authenticity tokens for standard forms. Rails handles most of it.

Common patterns

1. Rely on Rails form helpers

Developers use helpers like:

• form_with
• form_for in older apps
• form_tag

These helpers automatically include the token.

2. Keep CSRF protection enabled in ApplicationController

class ApplicationController < ActionController::Base
  protect_from_forgery with: :exception
end

This is the default pattern for browser-based Rails apps.

3. Send the token in custom JavaScript requests

When using fetch, axios, or custom front-end code, developers read the token from csrf_meta_tags and send it as a request header.

4. Use guardrails around APIs

Pure JSON APIs that do not rely on browser sessions often use token-based authentication instead of session cookies, and may disable CSRF protection for those endpoints if appropriate. This should be done carefully and intentionally.

Beginners often misunderstand what the authenticity token does.

1. Confusing it with authentication

Mistake: Thinking the token logs the user in or proves their identity.

The authenticity token does not replace:

• passwords
• sessions
• API tokens
• JWTs

It only helps prove that a request came from a trusted page in your app.

2. Removing the token from custom forms

Broken example:

<form action="/posts" method="post">
  <input type="text" name="title">
  <button type="submit">Create</button>
</form>

If this raw HTML is used in Rails without the token, the request may fail CSRF verification.

Use Rails helpers or add the token properly.

3. Forgetting the token in JavaScript requests

Broken example:

fetch('/posts', {
  : ,
  : {
    : 
  },
  : .({ :  })
});

Here are some useful comparisons.

Authenticity token vs session cookie

• Session cookie: tells Rails which logged-in user is making the request.

• Authenticity token: Rails security token used to prevent CSRF attacks.
• Main job: verify that a state-changing request came from a trusted page generated by your app.
• Usually included in:
  • POST
  • PATCH
  • PUT
  • DELETE
• Usually not needed for:
  • GET

Common Rails pieces

protect_from_forgery with: :exception

<%= form_with model: @post do |form| %>
  ...
<% end %>

<%= csrf_meta_tags %>

JavaScript header

'X-CSRF-Token': token

Hidden form field

<input type="hidden" name= =>

What is the authenticity token in Rails?

It is a security token Rails uses to help prevent CSRF attacks on state-changing requests.

Why does Rails include an authenticity token in forms?

Rails includes it so the server can verify that the submitted form came from your application, not from a malicious external site.

Is the authenticity token the same as a session cookie?

No. A session cookie identifies the user session, while the authenticity token helps verify the request source.

Do all Rails forms need an authenticity token?

Forms that change data usually do. Rails form helpers add it automatically for those cases.

Why do I get InvalidAuthenticityToken in Rails?

Usually because the request is missing the token, the token is invalid, the session expired, or a custom JavaScript request did not send the CSRF header.

Do GET requests need an authenticity token?

Normally no, because GET requests should only read data and not change server state.

How do I send the authenticity token with fetch in Rails?

Read it from the csrf-token meta tag and send it in the X-CSRF-Token request header.

Can I disable authenticity token checking in Rails?

Yes, but only when you understand the security implications. Disabling it carelessly can expose your app to CSRF attacks.

• CSRF (Cross-Site Request Forgery) — The attack the authenticity token is designed to prevent.
• Sessions in Rails — Sessions identify users and explain why browsers automatically sending cookies can create CSRF risk.
• Rails form helpers — Helpers like form_with automatically include authenticity tokens.
• HTTP methods — Understanding GET, POST, PATCH, PUT, and DELETE helps explain when CSRF protection matters.
• Request headers — JavaScript requests often send the CSRF token in a header.
• Authentication vs authorization — Helps separate login/security identity concepts from CSRF protection.
• API authentication — Useful for comparing browser session apps with token-based API apps.