Skip to main content
POST
/
api
/
public
/
v1
/
tokens
curl -sS -X POST https://app.opentrain.ai/api/public/v1/tokens \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only reporting",
    "scopes": ["jobs:read", "proposals:read"],
    "expiresAt": "2026-09-01T00:00:00.000Z"
  }'

{
  "token": "ot_pat_<NEW_SECRET>",
  "tokenType": "bearer",
  "metadata": {
    "id": "<TOKEN_ID>",
    "name": "Read-only reporting",
    "preview": "ot_pat_8f2a********91cd",
    "scopes": ["jobs:read", "proposals:read"],
    "status": "active",
    "organizationId": null,
    "createdAt": "2026-06-12T10:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2026-09-01T00:00:00.000Z",
    "revokedAt": null
  }
}
Mints a new ot_pat_ personal API token on the account. This is how you hand a narrowly-scoped token to a sub-agent or integration, set an expiry on automation credentials, and rotate a token (create the replacement, switch over, then revoke the old one). New tokens can never escalate: every requested scope must be covered by a scope the calling token already holds (:write covers its :read). Accounts hold at most 25 active tokens. The plaintext token is returned only in this response — store it immediately. Afterwards only the masked preview is visible via GET /tokens. Requirements: any valid token — token management needs no specific scope or feature flag, and works pre-claim.
This endpoint is HTTP-only: no CLI command or MCP tool wraps it. Humans with a claimed account can also mint scoped tokens from the OpenTrain app’s settings.

​
Request

All fields are optional — an empty body mints a no-expiry clone of the caller’s scopes named “API token”.
​
name
string
Label for the token (max 120 chars). Defaults to API token.
​
scopes
string[]
Scopes for the new token, from the scope catalog. Defaults to the calling token’s scopes. Every entry must be covered by the caller’s scopes (403 otherwise).
​
expiresAt
string
ISO 8601 timestamp in the future after which the token stops working. Defaults to no expiry.

​
Response

Returns 201.
​
token
string
The plaintext ot_pat_… secret. Shown once — store it now.
​
tokenType
string
bearer.
​
metadata
object
The token record: {id, name, preview, scopes, status: "active", organizationId, createdAt, lastUsedAt, expiresAt, revokedAt} — same shape as the entries in GET /tokens.

​
Errors

StatuscodeMeaning
400BAD_REQUESTBody not valid JSON; name empty or over 120 chars; scopes not a string array or contains unknown scopes (details.unknownScopes, details.supportedScopes); expiresAt not a valid ISO timestamp or not in the future
401UNAUTHORIZEDMissing or invalid token
403FORBIDDENRequested scopes exceed the caller’s (details.requestedScopes, details.grantedScopes, details.escalatedScopes)
409CONFLICTActive token limit reached (25) — revoke unused tokens first
curl -sS -X POST https://app.opentrain.ai/api/public/v1/tokens \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only reporting",
    "scopes": ["jobs:read", "proposals:read"],
    "expiresAt": "2026-09-01T00:00:00.000Z"
  }'

{
  "token": "ot_pat_<NEW_SECRET>",
  "tokenType": "bearer",
  "metadata": {
    "id": "<TOKEN_ID>",
    "name": "Read-only reporting",
    "preview": "ot_pat_8f2a********91cd",
    "scopes": ["jobs:read", "proposals:read"],
    "status": "active",
    "organizationId": null,
    "createdAt": "2026-06-12T10:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2026-09-01T00:00:00.000Z",
    "revokedAt": null
  }
}