Tokens

API tokens authenticate server-to-server requests for one organization. Token endpoints list, create, update, and revoke them.

Only an Owner signed in as a user can call these endpoints, with a user JWT and X-Organization-Slug. API tokens cannot manage tokens.

Method	Endpoint	Description
GET	/api/v2/tokens/	List API tokens
GET	/api/v2/tokens/{id}/	Retrieve a token
POST	/api/v2/tokens/	Create a token
PATCH	/api/v2/tokens/{id}/	Update a token
DELETE	/api/v2/tokens/{id}/	Delete a token

The token object

{
  "id": 12,
  "name": "Point export pipeline",
  "info": "Nightly ETL job",
  "token_type": "api",
  "is_active": true,
  "expires_at": "2026-12-31T23:59:59+08:00",
  "created_at": "2026-01-08T10:00:00Z",
  "last_used_at": "2026-02-15T02:00:00Z",
  "access_config": {
    "role": "manager",
    "role_display": "Manager",
    "all_projects": false,
    "projects": ["proj_greenhouse", "proj_coldroom"]
  }
}

Field	Type	Description
id	integer	Token ID
token	string	Secret value. Returned only by Create a token.
name	string	Label
info	string | null	Note
token_type	string	api
is_active	boolean	Inactive tokens are rejected
expires_at	string | null	Expiry time; null never expires
created_at	string	Creation time
last_used_at	string | null	Time of the last successful request
access_config.role	string	readonly, operator, or manager
access_config.all_projects	boolean	true covers all projects
access_config.projects	string[]	project_id values when all_projects is false

List tokens

GET /api/v2/tokens/

Returns the organization's API tokens, newest first. The secret value is omitted.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Example request

curl 'https://dl.yengear.com/api/v2/tokens/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear'

Responses

• 200: Array of token objects.
• 403: The caller is not an Owner, or the request used an API token.

Retrieve a token

GET /api/v2/tokens/{id}/

Returns one token without its secret value.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
id	integer	Yes	Token ID

Responses

• 200: The token object.
• 404: The token does not belong to the organization.

Create a token

POST /api/v2/tokens/

Creates an API token and returns its secret value once.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Request body

Name	Type	Required	Description
name	string	Yes	Label
info	string	No	Note
expires_at	string	No	ISO 8601 time with a timezone offset. Omit or send null for no expiry.
is_active	boolean	No	Defaults to true
access_config	object	Yes	Role and project scope
access_config.role	string	No	readonly (default), operator, or manager. owner is rejected.
access_config.all_projects	boolean	No	Defaults to false
access_config.projects	string[]	Conditional	Required and non-empty when all_projects is false. Each ID must exist in the organization.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/tokens/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Webhook relay",
    "expires_at": "2026-12-31T23:59:59+08:00",
    "access_config": { "role": "operator", "all_projects": false, "projects": ["proj_greenhouse"] }
  }'

Example response

{
  "success": true,
  "data": {
    "id": 13,
    "token": "rjm9czn9...",
    "name": "Webhook relay",
    "info": null,
    "token_type": "api",
    "is_active": true,
    "expires_at": "2026-12-31T23:59:59+08:00",
    "created_at": "2026-02-16T09:00:00Z",
    "last_used_at": null,
    "access_config": { "role": "operator", "role_display": "Operator", "all_projects": false, "projects": ["proj_greenhouse"] }
  },
  "error": null
}

Responses

• 201: The token object, including token.
• 400: Missing access_config, invalid role, empty project scope, unknown project ID, or invalid expires_at.
• 403: The caller is not an Owner, or the request used an API token.

Update a token

PATCH /api/v2/tokens/{id}/

Updates a token's label, status, expiry, or permissions. PUT behaves the same as PATCH. Changes apply from the token's next request.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
id	integer	Yes	Token ID

Request body

Any of name, info, is_active, expires_at, and access_config. Inside access_config, omitted keys keep their current values.

Example request

curl -X PATCH 'https://dl.yengear.com/api/v2/tokens/13/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{"is_active": false, "access_config": {"role": "readonly"}}'

Responses

• 200: The updated token object, without token.
• 400: Validation error, as for Create a token.
• 404: The token does not belong to the organization.

Delete a token

DELETE /api/v2/tokens/{id}/

Revokes a token permanently. Later requests with it fail with 403.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user).

Path parameters

Name	Type	Required	Description
id	integer	Yes	Token ID

Responses

• 204: Token deleted.
• 404: The token does not belong to the organization.

Rotate a token

1. Create a token with the same role and scope.
2. Move clients to the new token.
3. Set is_active to false on the old token, then delete it.

The organization audit log records token creation, updates, and deletion.

Related

• Authentication
• Access tokens and permissions