Create Token

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.

This endpoint always mints fixed fine-grained scopes — the explicit list you request, or a clone of the caller’s current scopes. Full-access keys, which automatically expand to current and future self-serve scopes, can only be created in Developer Settings in the web app; the API cannot mint one.

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.

Note

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”.

namestringbody

Label for the token (max 120 chars). Defaults to API token.

scopesstring[]body

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).

expiresAtstringbody

ISO 8601 timestamp in the future after which the token stops working. Defaults to no expiry.

Response

Returns 201.

tokenstring

The plaintext ot_pat_… secret. Shown once — store it now.

tokenTypestring

bearer.

metadataobject

The token record: {id, name, preview, scopes, status: "active", organizationId, createdAt, lastUsedAt, expiresAt, revokedAt} — same shape as the entries in GET /tokens.

Errors

Status	code	Meaning
400	BAD_REQUEST	Body 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
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Requested scopes exceed the caller’s (details.requestedScopes, details.grantedScopes, details.escalatedScopes)
409	CONFLICT	Active token limit reached (25) — revoke unused tokens first

Request examples

curl

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"
  }'

Response examples

201403 (scope escalation)

201

{
  "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
  }
}

403 (scope escalation)

{
  "error": "Requested scopes exceed the scopes of the authenticating token.",
  "code": "FORBIDDEN",
  "requestId": "<REQUEST_ID>",
  "details": {
    "requestedScopes": ["payments:write"],
    "grantedScopes": ["jobs:read", "jobs:write", "proposals:read"],
    "escalatedScopes": ["payments:write"]
  }
}