Skip to content
Port OS

Create Token

← HTTP API reference
View source specification ↗
POST /tokens

Creates an expiring, revocable bearer access key for the caller. The raw JWT is returned only once. Use purpose WEBSITE_LOGIN for full-account website sign-in and explicit OAuth consent, or API for automation (the default). Subject must be ~self or the authenticated principal's own identifier. Website keys cannot have restricted scopes, expire within seven days and require an existing Google account session to create. Vended and delegated credentials cannot create independent replacement keys. Website keys cannot be refreshed or exchanged for identity sessions. OAuth connections approved with a website key are independently revocable.

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

Required scope

Any authenticated access token

Request body

Fields

purposestring

API keys authenticate automation. WEBSITE_LOGIN keys grant full account website sign-in and explicit OAuth consent, cannot have restricted scopes, and must be created through an existing account sign-in. Keys expire and can be revoked; OAuth connections approved with a website key are revoked separately.

Default: API

Allowed values: API, WEBSITE_LOGIN.

subjectstring

Identity for the token. Use ~self for the current user (resolved to the authenticated principal at create time), or that same principal's full path. Other principals are rejected.

expires_ininteger

Lifetime in seconds, default 3600. Website sign-in keys require a positive lifetime of at most 604800 (seven days).

scopestring

Space-separated scopes. Optional; default no scopes. See scopes documentation for allowed values and semantics.

labelstring

Optional human-readable label for the token (e.g. "CLI token").

Returns

200

Token created successfully. The raw JWT is returned only once.

Fields

idstringRequired

Token identifier (same as JWT jti). Use for list/delete and in the DELETE URL.

tokenstringRequired

The raw JWT. Returned only once at creation; cannot be retrieved again.

expires_atstringRequired

When the token expires (ISO 8601).

format: "date-time"

Errors

400

Invalid request (e.g. invalid subject, malformed body)

Check the request fields and any validation details, then correct the payload.

401

Unauthorized

Obtain a valid access token, then retry.

403

Forbidden - not allowed to create a token for the given subject

Check the linked account and its permissions for the device or resource.

500

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.