Token-Based Authentication in Web Frameworks
Comparing stateless authentication patterns in Rails and Laravel ecosystems

Devise Token Auth stores tokens in the database. Each successful authentication generates a new token and stores it in the tokens column (a JSON hash). The token is sent in response headers, not the body.

# app/controllers/api/v1/auth/sessions_controller.rb
class Api::V1::Auth::SessionsController < DeviseTokenAuth::SessionsController
  def create
    # POST /api/v1/auth/sign_in
    # Params: { email: "alice@example.com", password: "..." }
    # Response headers:
    #   access-token: "abc123..."
    #   client: "xyz789..."
    #   uid: "alice@example.com"
    super
  end
end

The client must include three headers on subsequent requests: access-token, client, and uid. The server validates by querying the database for a user record matching the uid and comparing the token hash.

# Subsequent request
# Headers:
#   access-token: "abc123..."
#   client: "xyz789..."
#   uid: "alice@example.com"

# Server validates:
# 1. Load user by uid
# 2. Check tokens[client] matches access-token
# 3. Verify token expiry

Token renewal happens on every request. The server issues a new token and invalidates the old one. This creates a race condition: if the client sends two concurrent requests with the same token, the second request may fail because the first already rotated the token. Devise Token Auth handles this with a configurable batch window (default: 2 weeks) during which old tokens remain valid.

JWT Auth does not store tokens. The server signs the token with a secret key; validation is signature verification, not database lookup. This is the stateless property.

// app/Http/Controllers/AuthController.php
use Tymon\JWTAuth\Facades\JWTAuth;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        // POST /api/auth/login
        // Body: { "email": "alice@example.com", "password": "..." }
        $credentials = $request->only('email', 'password');

        if (!$token = JWTAuth::attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        // Response body:
        // { "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer" }
        return response()->json(['access_token' => $token, 'token_type' => 'bearer']);
    }
}

The client includes the token in the Authorization header as a bearer token. The server decodes and verifies the signature. No database query is required for validation.

// Subsequent request
// Header: Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Middleware validates:
// 1. Decode JWT
// 2. Verify signature with secret key
// 3. Check expiration claim (exp)
// 4. Optionally load user from database using sub claim

Token renewal requires an explicit refresh endpoint. The client sends the old token to /api/auth/refresh and receives a new token. The old token is blacklisted by storing its jti (JWT ID) in a cache or database until expiry.

public function refresh()
{
    // POST /api/auth/refresh
    // Header: Authorization: Bearer <old_token>
    $newToken = JWTAuth::refresh(JWTAuth::getToken());
    return response()->json(['access_token' => $newToken]);
}

Revocation is deletion. Remove the token from the database tokens column and it is invalid immediately.

# app/controllers/api/v1/auth/sessions_controller.rb
def destroy
  # DELETE /api/v1/auth/sign_out
  # Removes client token from user.tokens hash
  super
end

# Implementation (inside DeviseTokenAuth)
user.tokens.delete(client_id)
user.save!

This requires a database write on every logout. At scale, the tokens column becomes a contention point. The column stores a JSON hash of all active sessions; concurrent updates require optimistic locking.

JWT Auth uses a blacklist. When a token is revoked, its jti claim is added to a blacklist table or cache. Validation checks the blacklist before accepting the token.

public function logout()
{
    // POST /api/auth/logout
    // Blacklists the current token by jti
    JWTAuth::invalidate(JWTAuth::getToken());
    return response()->json(['message' => 'Successfully logged out']);
}

// Middleware must now check blacklist on every request
// This reintroduces state and database lookups

The blacklist entry only needs to live until the token's exp claim. After expiry, the token is invalid regardless of blacklist status. This allows automatic cleanup: delete blacklist entries older than the maximum token TTL.

The blacklist defeats statelessness. Every validation now requires a cache or database query to check if the jti is blacklisted. The advantage over Devise Token Auth is granularity: the blacklist only contains revoked tokens, not all active sessions.

# Gemfile
gem 'devise_token_auth'

# config/routes.rb
mount_devise_token_auth_for 'User', at: 'api/v1/auth'

# app/models/user.rb
class User < ApplicationRecord
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :validatable
  include DeviseTokenAuth::Concerns::User
end

# Database migration
create_table :users do |t|
  t.string :email, null: false
  t.string :encrypted_password, null: false
  t.text :tokens  # JSON hash of active tokens
  t.timestamps
end

add_index :users, :email, unique: true

The tokens column format is a hash keyed by client ID. Each entry contains the token hash, expiry, and last refresh time.

{
  "xyz789": {
    "token": "$2a$10$...",
    "expiry": 1653532800,
    "last_token": "$2a$10$...",
    "updated_at": "2026-05-22T12:00:00.000Z"
  }
}

// composer.json
{
  "require": {
    "tymon/jwt-auth": "^2.0"
  }
}

// config/auth.php
'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

// app/Models/User.php
use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    public function getJWTIdentifier()
    {
        return $this->getKey();  // Primary key
    }

    public function getJWTCustomClaims()
    {
        return [];  // Additional payload data
    }
}

// routes/api.php
Route::post('auth/login', [AuthController::class, 'login']);
Route::post('auth/logout', [AuthController::class, 'logout'])->middleware('auth:api');
Route::post('auth/refresh', [AuthController::class, 'refresh'])->middleware('auth:api');

The JWT payload contains the user ID in the sub claim. The server loads the user on each request if needed, but validation does not require a database query.

{
  "iss": "https://api.example.com",
  "sub": "42",
  "iat": 1653532800,
  "exp": 1653536400,
  "jti": "a7b3c4d5e6f7"
}

Devise Token Auth sends tokens in custom headers (access-token, client, uid). This prevents CSRF attacks because browsers do not automatically send custom headers on cross-origin requests.

JWT Auth uses the Authorization: Bearer header. Same CSRF protection, but the standard header makes it compatible with OAuth2 clients and tools that expect bearer tokens.

Both require the client to store the token. Storing in localStorage is vulnerable to XSS. Storing in an httpOnly cookie prevents XSS access but reintroduces CSRF risk unless combined with SameSite=Strict.

The recommended pattern for SPA clients: store in memory and refresh on page load using a short-lived refresh token in an httpOnly cookie.

JWT Auth is vulnerable to algorithm downgrade attacks if the server accepts tokens with alg: none. The mitigation is to explicitly specify allowed algorithms in the validation configuration.

// config/jwt.php
'algo' => 'HS256',  // Never allow 'none'

Devise Token Auth does not use JWTs, so this attack does not apply. The token is a random string hashed with bcrypt.

Rotating the signing secret in JWT Auth invalidates all tokens immediately. This is a feature for emergency revocation but requires coordination: issue new tokens with the new secret before rotating, then deprecate the old secret after a grace period.

Devise Token Auth tokens are hashed, not signed. Rotating the secret is not applicable. Individual token revocation is deletion.