API tokens

Use API tokens for release automation and other routes that explicitly accept bearer credentials. Token administration uses a GitHub dashboard session: an API token cannot create, list, or revoke tokens, even if it has admin scope. An organization admin can manage tokens under Settings → Tokens or through the endpoints below.

Endpoints

Method and path	Authentication	Success
GET /api/v1/orgs/:orgId/tokens	Admin session	200 list
POST /api/v1/orgs/:orgId/tokens	Admin session	201 created token
POST /api/v1/orgs/:orgId/tokens/:tokenId/revoke	Admin session	200 revoked token
GET /api/v1/token/whoami	Valid rd_ bearer token	200 token identity

The list returns { "items": [...] }, newest first. Each entry includes id, orgId, appId, name, tokenPrefix, scopes, lastUsedAt, expiresAt, revokedAt, and createdAt. It includes revoked tokens, so filter on revokedAt in a token management UI. Plaintext token values are never returned by the list route.

Create a token

POST /api/v1/orgs/org_123/tokens
Content-Type: application/json

{
  "name": "Field Notes release CI",
  "appId": "app_456",
  "scopes": ["read", "upload", "promote"],
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

name must contain 1–100 characters. scopes needs at least one of read, upload, promote, or admin. appId and expiresAt are optional. An omitted appId creates an organization-wide token; if supplied, it must identify an app in this organization. An omitted expiresAt makes a token without a scheduled expiry. Store the returned token value immediately: the server shows it only in this 201 response. The rest of the response has the same metadata as a list item.

Creation is limited to ten requests per minute per rate-limit key. If you receive 429, honor the Retry-After header. A token created for an app in another organization returns 404 app_not_found.

Use and inspect a token

Send the value in the Authorization header:

curl -H "Authorization: Bearer $RD_TOKEN" \
  "$RD_URL/api/v1/token/whoami"

The response is { "orgId": "org_123", "appId": "app_456", "scopes": ["read", "upload", "promote"] }. appId is null for an organization-wide token. A missing, expired, or revoked token returns 401 unauthorized.

Scope	Current token-enabled operations
read	Read an individual app
upload	Upload an artifact and edit release notes
promote	Promote, demote, pause, resume, roll back, and revoke releases
admin	Satisfy a scope check on any route that accepts a token

The app restriction and organization restriction still apply with admin scope. Many dashboard routes are session-only, including release list and detail, app creation, signing keys, tester distribution, and external-store publication. Check each reference page's authentication column before building a CI job.

Revoke a token

Call POST /api/v1/orgs/:orgId/tokens/:tokenId/revoke with an admin session. The response is the token metadata with revokedAt set. Repeating the call for an already revoked token returns its existing metadata. The token stops authenticating immediately; a later call to whoami receives 401. An unknown token ID in this organization returns 404 token_not_found.

For the first release automation flow, see Publish your first release. For the exact session and role rules, see Authentication and access.