Skip to main content

​
POST /api/v1/auth/logout

Revokes a refresh token to end a user session. After logout, the refresh token can no longer be used to obtain new access tokens.

​
Request Body

​
refreshToken
string
required
The JWT refresh token to revokeAfter revocation, this token cannot be used for token refresh.

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
​
message
string
Confirmation messageValue: "Logged out successfully"

​
Error Responses

This endpoint is designed to be fault-tolerant and will always return a 200 success response, even if:
  • The refresh token is invalid
  • The refresh token has already been revoked
  • The refresh token has expired
  • The refresh token is malformed
This behavior prevents information leakage about token validity. 
curl -X POST https://api.example.com/api/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

​
Session Management

The logout endpoint is part of a comprehensive session management system:

​
Single Session Logout

The /api/v1/auth/logout endpoint revokes a single refresh token, ending one session.

​
Multi-Device Support

The system tracks multiple active sessions per user:
  • Each device can have its own active session
  • Sessions are identified by deviceId and tracked with:
    • Device name (e.g., “Chrome · Windows”)
    • IP address
    • User agent
    • Last used timestamp
    • Creation timestamp

Logout All Sessions

Revoke all active sessions for the authenticated userEndpoint: POST /api/v1/auth/logout/all

Get User Sessions

List all active sessions for a user (requires authentication)Endpoint: GET /api/v1/auth/sessions/user/:userId

Revoke Specific Session

Revoke a specific session by ID (requires authentication)Endpoint: DELETE /api/v1/auth/sessions/:sessionId

​
Token Revocation Details

When a token is successfully revoked:
  • The token is marked with revoked: true in the database
  • A revokedAt timestamp is recorded
  • The revokedReason is set to "logout"
  • The token can no longer be used for refresh operations

​
Security Considerations

  • Access tokens remain valid - This endpoint only revokes the refresh token. The current access token will remain valid until it expires (typically a short duration). For immediate session termination across all tokens, consider implementing access token blacklisting or using short-lived access tokens.
  • Silent failure - The endpoint doesn’t reveal whether a token was valid or not, preventing attackers from testing token validity.
  • Client-side cleanup - After logout:
    • Clear both access and refresh tokens from storage
    • Redirect to the login page
    • Clear any cached user data

​
Example: Complete Logout Flow

// Complete logout implementation
async function logout() {
  const refreshToken = localStorage.getItem('refreshToken');
  
  if (refreshToken) {
    try {
      // Call logout endpoint
      await fetch('https://api.example.com/api/v1/auth/logout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ refreshToken })
      });
    } catch (error) {
      // Log error but continue with cleanup
      console.error('Logout request failed:', error);
    }
  }
  
  // Always clear local storage
  localStorage.removeItem('accessToken');
  localStorage.removeItem('refreshToken');
  localStorage.removeItem('user');
  
  // Redirect to login
  window.location.href = '/login';
}

Build docs developers (and LLMs) love

Get started for freeTalk to us