API Tokens

Manage programmatic access for your automation and tools

Use API tokens to interact with Redirect Manager programmatically using persistent credentials.

Overview

API tokens allow external systems (like CI/CD pipelines or scripts) to manage redirects without using person-specific session tokens. Currently, only ADMIN users can create and manage API tokens.

Authentication

All API requests require authentication using a Bearer token in the Authorization header. Admin session is required for managing these tokens.

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Required	Bearer token (JWT Session) for API authentication Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`

Example:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET

/api/v1/api-tokens

List API Tokens

Returns a list of all active API tokens for the authenticated user.

Response Structure

Returns an array of token metadata.

200 OK

Success. Returns tokens list.

Example Response:

[
  {
    "id": "uuid-token-1",
    "name": "CI/CD Token",
    "scope": "READ_WRITE",
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "createdAt": "2023-01-01T00:00:00.000Z"
  }
]

POST

/api/v1/api-tokens

Create API Token

Creates a new API token. Note: The token value is only returned once upon creation.

Request Body

Provide the token name and its permissions.

Parameters:

Parameter	Type	Required	Description
`name`	string	Required	A descriptive name for the token (e.g., CI/CD) Example: `My App Token`
`scope`	enum (READ, READ_WRITE)	Required	Permission level for the token. Example: `READ_WRITE`
`expiresAt`	string (ISO Date)	Required	The expiration timestamp for the token. Example: `2025-12-31T23:59:59Z`

Example:

{
  "name": "External Script",
  "scope": "READ_WRITE",
  "expiresAt": "2025-06-01T12:00:00Z"
}

Response Structure

Returns the created token metadata AND the literal token secret.

201 Created

Created. Returns the actual token value.

Example Response:

{
  "id": "uuid-token-2",
  "name": "External Script",
  "scope": "READ_WRITE",
  "token": "rm_abc123tokensecretval...",
  "expiresAt": "2025-06-01T12:00:00Z",
  "createdAt": "2023-01-01T00:00:00.000Z"
}

DELETE

/api/v1/api-tokens/:id

Revoke API Token

Immediately invalidates and removes an API token.

Path Parameters

Required Parameters:

Parameter	Type	Required	Description
`id`	string	Required	The unique ID of the token to revoke Example: `uuid-token-1`

Response Structure

Standard response status codes.

204 Response

No Content. Token revoked successfully.