Skip to main content

Revoke Session

Individual API

Revoke a specific session by ID.

Description​

The Revoke Session endpoint immediately terminates a specific authentication session, invalidating its access token and preventing any further API requests using that session. This is a critical security endpoint that allows users to immediately revoke access when a session is compromised, a device is lost, or suspicious activity is detected.

This endpoint is part of the Sessions API and provides granular control over session management. Once a session is revoked, all API requests using that session's access token will fail with a 401 Unauthorized error, effectively logging out that specific session.

Use Cases​

  • Security Response: Immediately revoke access when a session is compromised or suspicious activity is detected
  • Device Management: Terminate sessions from lost, stolen, or no longer used devices
  • Access Control: Manage active sessions and revoke access from specific devices or locations
  • Security Audit: Remove sessions identified as suspicious during session review

Workflow Context​

This endpoint is typically used:

  • After reviewing the list of active sessions to identify sessions to revoke
  • When a device is lost, stolen, or suspected of being compromised
  • When detecting suspicious login activity or unauthorized access
  • During security audits to remove old or unused sessions
  • To manage sessions across multiple devices and browsers

Prerequisites​

  • User must be authenticated with a valid access token
  • User must know the session ID (obtainable from List Sessions)
  • Session must exist and belong to the authenticated user
Outline

Endpoint​

DELETE /api/v1/sessions/{session_id}

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>

Path Parameters​

ParameterTypeRequiredDescription
session_idintegerYesUnique identifier of the session to revoke. You can obtain session IDs from the List Sessions endpoint.

Response​

Success (204)​

No content returned.

Error Codes​

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing authentication token. Ensure you include a valid Bearer token in the Authorization header.
404SESSION_NOT_FOUNDThe specified session ID was not found or does not belong to the authenticated user. Verify the session ID using the List Sessions endpoint.
422VALIDATION_ERRORInvalid session ID format. Ensure the session ID is a valid integer.

For more information on error handling, see Error Handling.

Features​

  • Immediate Revocation: Session is revoked immediately upon successful request
  • Token Invalidation: The access token associated with the session is immediately invalidated
  • User Verification: Ensures only the session owner can revoke their own sessions
  • Security Audit Logging: All revocation events are logged for security monitoring and compliance
  • Idempotent Operation: Revoking an already-revoked session returns success without error

Important Security Notes​

  • Immediate Effect: Session revocation takes effect immediately. Any API requests using the revoked session's token will fail with 401 Unauthorized.
  • No Recovery: Once revoked, the session cannot be restored. The user must create a new session by logging in again.
  • Current Session: You can revoke the current session (the one used for this API call), but you will need to authenticate again for subsequent requests.
  • Multiple Sessions: To revoke all sessions at once, use the Logout All endpoint.

Example​

curl -X DELETE https://api.rivergen.com/api/v1/sessions/123 \
  -H "Authorization: Bearer <access_token>"
  • List Sessions - View all active sessions to identify session IDs (prerequisite)
  • Logout - End the current session
  • Logout All - Revoke all sessions at once
  • Login - Create a new session after revocation

See Also​