Sign in
Tokens

Issue a personal access token

Changed on

Issuance is session-authenticated — a logged-in user mints PATs via the web app. PATs cannot mint other PATs (chicken-and-egg). The raw secret is returned exactly once.

post/api/v1/tokens

Request

  • Base URL: http://localhost:3000
  • URL: http://localhost:3000/api/v1/tokens
  • Auth: API key in cookie sb-fmbpikzpkafptqximhxn-auth-token

Request body

namestring

Human-readable label shown in the token-management UI.

scopesstring[] required

Scopes granted to this token. At least one required. Requesting workspace:admin makes workspace_id MANDATORY — omitting it returns 403 forbidden — and additionally requires the caller to hold the role admin or owner in that workspace; any other role returns 403. Both guards run after schema validation, so the enum accepting the value is not a grant. See ADR-0005.

workspace_idstring uuid

Restrict the token to a single workspace. Omit for cross-workspace tokens (non-admin scopes only). When supplied, the caller must be an ACTIVE member of that workspace — a non-member or a non-active membership returns 403 forbidden.

expires_in_daysinteger

TTL in days. Omit for non-expiring tokens. Max 365.

Example request

{
  "name": "ci-pipeline"
}

Response

Token created. Capture the token field — it is unrecoverable.

idstring uuid required
tokenstring required

Raw PAT in the form bk_pat_<prefix>.<secret>. Shown ONCE in this response. The server only stores SHA-256(secret).

namestring nullable required
scopesstring[] required
workspace_idstring uuid nullable required
expires_atstring date-time nullable required
created_atstring date-time required
warningstring required

Example response

{
  "token": "bk_pat_AbCdEfGhIjKl.MnOpQrStUv...",
  "warning": "Store this token now — it cannot be retrieved later."
}

Changes

  • 4528999528c6Revision changes
    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

  • 2ca74ff5fec5Revision changes
    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status