User session API

The User Session API provides capabilities for managing user sessions. Like the endpoints in the end user API, the session endpoints are only accessible with valid API client credentials. These endpoints can be used by a web application to list active sessions for a specific user. For example, the web application might want to display a list of active sessions to the user, including details such as session ID, authentication time, last issued access time, user agent, and location information.

In addition to listing sessions, this API also allows for terminating user sessions. These termination endpoints provide a layer of security and control over user sessions. They ensure that old and inactive sessions can be properly ended as needed, maintaining the integrity of the user's active sessions.

List user sessions

This endpoint requires basic authentication using the API client credentials.

Endpoint: GET /oauth/api/v1/users/{userId}/sessions

If the user does not exist, or if the user has no active sessions, a 404 Not Found is returned. If there are active sessions, a response is returned with an array of session details.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "result": [
    {
      "session_id": "8f4ecb2b-7bc1-47bc-95e1-0b02ae4b6e32",
      "auth_time": "2023-11-13T09:31:49.231460Z",
      "last_iat": "2023-11-13T09:31:49.340Z",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/119.0",
      "location": {
        "ip_address": "10.0.0.1"
      },
      "clients": [
        {
          "id": "my-client",
          "name": "my-client"
        }
      ]
    }
  ]
}

Example error response

{
  "error": "No sessions found"
}

End user sessions

Both of the end user session endpoints are invaluable security tools that help you administer user sessions. They enable you to ensure that older, unused sessions are appropriately terminated, thereby enhancing your control over the user authentication process.

End all sessions

This secure endpoint requires authentication using API credentials. It has been designed to delete every active session of a specified user.

The default behavior is to remove the associated tokens as well.

Endpoint: DELETE /oauth/api/v1/users/{userId}/sessions

After successful deletion, a 204 No Content status is returned. If the user doesn't exist or has no active sessions, it also results in a 204 No Content being returned.

Query parameters

End a specific session

This endpoint, protected by authentication via client credentials, removes an individual session of the user. By default, the associated tokens are also removed.

Endpoint: DELETE /oauth/api/v1/users/{userId}/sessions/{sessionId}

After successful deletion, you receive a 204 No Content status. If the user or the session is nonexistent, a status 204 No Content is also returned.

Query parameters