Revoke Session

​

Endpoint

POST /recipe/session/remove

​

Request Body

["session-handle-1", "session-handle-2"]

​

Response

["session-handle-1", "session-handle-2"]

​

Example Requests

​

Revoke by Session Handles

curl -X POST https://your-domain.com/recipe/session/remove \
  -H "Content-Type: application/json" \
  -d '{
    "sessionHandles": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
    ]
  }'

​

Revoke All Sessions for User

curl -X POST https://your-domain.com/recipe/session/remove \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "revokeAcrossAllTenants": true,
    "revokeSessionsForLinkedAccounts": true
  }'

​

Revoke User Sessions in Current Tenant Only

curl -X POST https://your-domain.com/recipe/session/remove \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "revokeAcrossAllTenants": false,
    "revokeSessionsForLinkedAccounts": false
  }'

​

Example Response

{
  "status": "OK",
  "sessionHandlesRevoked": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
  ]
}

​

Implementation Details

​

Source Code Reference

• API Handler: View source
• Session Logic: View source

​

Revocation Process

​

Revoke by Session Handles

1. Extract Tenant IDs - Parse tenant ID from each session handle
2. Group by Tenant - Organize session handles by tenant
3. Revoke per Tenant - Delete sessions in each tenant’s storage
4. Aggregate Results - Combine all revoked session handles

​

Revoke by User ID

1. Resolve User Mapping - Convert external user ID to internal if mapping exists
2. Determine Scope - Check revokeAcrossAllTenants and revokeSessionsForLinkedAccounts
3. Find Sessions - Query all non-expired session handles for the user
4. Include Linked Accounts - Optionally include sessions for linked accounts
5. Revoke Sessions - Delete all found session handles
6. Update Activity - Record user activity timestamp

​

Multi-Tenant Handling

• Default tenant: <uuid>
• Named tenant: <uuid>_<tenantId>

1. Extracts tenant ID from each handle
2. Loads appropriate tenant storage
3. Deletes sessions in their respective tenants

​

Linked Accounts

1. Resolves the primary user for the given user ID
2. Retrieves all linked login methods
3. Revokes sessions for all linked user IDs

​

Use Cases

​

User Logout

// Logout single session
async function logout(sessionHandle) {
  const response = await fetch('https://your-domain.com/recipe/session/remove', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      sessionHandles: [sessionHandle]
    })
  });
  
  const data = await response.json();
  
  if (data.status === 'OK') {
    // Clear client-side session data
    localStorage.clear();
    // Redirect to login
    window.location.href = '/login';
  }
}

​

Logout from All Devices

// Revoke all sessions for the current user
async function logoutAllDevices(userId) {
  const response = await fetch('https://your-domain.com/recipe/session/remove', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId,
      revokeAcrossAllTenants: true,
      revokeSessionsForLinkedAccounts: true
    })
  });
  
  const data = await response.json();
  
  if (data.status === 'OK') {
    console.log(`Revoked ${data.sessionHandlesRevoked.length} sessions`);
  }
}

​

Administrative Session Management

// Admin endpoint to revoke user sessions
async function adminRevokeUserSessions(userId, tenantId) {
  const response = await fetch('https://your-domain.com/recipe/session/remove', {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer admin-token'
    },
    body: JSON.stringify({
      userId,
      revokeAcrossAllTenants: false,  // Only in specific tenant
      revokeSessionsForLinkedAccounts: false
    })
  });
  
  return await response.json();
}

​

Security Response

// Revoke sessions after password change
async function revokeSessionsAfterPasswordChange(userId, currentSessionHandle) {
  const response = await fetch('https://your-domain.com/recipe/session/remove', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId,
      revokeAcrossAllTenants: true,
      revokeSessionsForLinkedAccounts: true
    })
  });
  
  const data = await response.json();
  
  // All sessions revoked including current one
  // User needs to log in again with new password
  return data.sessionHandlesRevoked;
}

​

Security Considerations

​

Immediate Revocation

​

Revocation Scope

​

User ID Mapping

• Accepts external user IDs
• Resolves to internal SuperTokens user IDs
• Revokes sessions associated with the internal ID
• Updates activity tracking correctly

​

Best Practices

1. Always Revoke on Logout - Prevent session reuse by revoking sessions when users log out
2. Revoke on Password Change - Invalidate all sessions when users change passwords
3. Revoke on Security Events - Immediately revoke sessions on suspicious activity
4. Use Linked Accounts Flag - When revoking by user ID, consider linked accounts
5. Log Revocations - Audit log all session revocations for security monitoring
6. Clear Client State - Clear client-side tokens after successful revocation

​

Error Handling

​

Invalid Parameters

• Both userId and sessionHandles are provided
• Neither userId nor sessionHandles are provided
• revokeAcrossAllTenants is used without userId
• revokeSessionsForLinkedAccounts is used without userId
• sessionHandles is an empty array

​

Partial Revocation

• Only valid, existing sessions are revoked
• Invalid or non-existent session handles are silently ignored
• Response includes only successfully revoked handles

​

Tenant Handling

• The system silently skips sessions from deleted tenants
• Other sessions are still revoked successfully
• No error is returned

​

Response Interpretation

​

Empty Revocation List

• By Session Handles: All provided handles were already revoked or invalid
• By User ID: User has no active sessions

​

Partial Revocation

• Some session handles were already revoked
• Some session handles didn’t exist
• Some sessions were in deleted tenants

​

Performance Considerations

​

Revoke by User ID

1. Query all sessions for the user (potentially across multiple tenants)
2. For linked accounts, query sessions for each linked user
3. Delete all found sessions

​

Revoke by Session Handles

1. Direct deletion of specified sessions
2. No queries needed to find sessions
3. Scales linearly with number of handles