Snapbooks logo Snapbooks Developer

OAuth Admin

Admin endpoints for managing OAuth refresh tokens across the system. These endpoints are restricted to admin users and provide the ability to list active tokens and revoke them by user, client, or individual token ID.

For general OAuth2 authentication flows and client management, see OAuth2 Authentication and OAuth Clients.

Endpoints

Method Endpoint Description
GET /oauth/admin/tokens List refresh tokens
POST /oauth/admin/tokens/revoke Revoke refresh tokens

List Tokens

GET /api/v2/oauth/admin/tokens

Returns a list of OAuth refresh tokens. By default, only active (non-revoked, non-expired) tokens are returned. Results can be filtered by user or client.

Requires admin access.

Query Parameters

Parameter Type Required Description
user_id integer No Filter tokens by user ID
client_id string No Filter tokens by OAuth client ID
active_only string No Set to true (default) to return only non-revoked, non-expired tokens. Any other value returns all tokens

Example Request

GET /api/v2/oauth/admin/tokens?user_id=42&active_only=true

Response

{
  "tokens": [
    {
      "id": 123,
      "user_id": 42,
      "client_id": "AbCdEfGhIjKlMnOpQrStUv",
      "client_name": "My Accounting App",
      "scope": "read:accounts write:transactions",
      "revoked": false,
      "expires_at": 1712764800,
      "created_at": "2026-04-09T10:30:00"
    }
  ]
}

Response Fields

Field Type Description
id integer Token ID
user_id integer The user this token belongs to
client_id string The OAuth client ID
client_name string Human-readable client name, or "Unknown" if the client no longer exists
scope string OAuth scopes granted to the token
revoked boolean Whether the token has been revoked
expires_at integer Unix timestamp when the token expires
created_at string ISO 8601 timestamp when the token was created, or null

Error Responses

Status Description
400 Not authenticated or not an admin user
400 Invalid user_id (not a valid integer)

Revoke Tokens

POST /api/v2/oauth/admin/tokens/revoke

Revokes OAuth refresh tokens. You can revoke a single token by ID, or bulk-revoke all tokens matching a user and/or client filter.

Requires admin access.

Request Body

Field Type Required Description
token_id integer Conditional ID of a specific token to revoke. If provided, user_id and client_id are ignored
user_id integer Conditional Revoke all tokens for this user. Can be combined with client_id
client_id string Conditional Revoke all tokens for this client. Can be combined with user_id

At least one of token_id, user_id, or client_id must be provided.

Revoke a Single Token

{
  "token_id": 123
}

Response (200 OK)

{
  "status": "success",
  "message": "Token 123 revoked"
}

Revoke by Criteria

{
  "user_id": 42,
  "client_id": "AbCdEfGhIjKlMnOpQrStUv"
}

Response (200 OK)

{
  "status": "success",
  "count": 3,
  "message": "3 tokens revoked"
}

Error Responses

Status Description
400 Not authenticated or not an admin user
400 Invalid token_id (not a valid integer)
400 Invalid user_id (not a valid integer)
400 None of token_id, user_id, or client_id provided
404 Token with the specified token_id not found