Skip to navigation
API referenceOrganizationsService tokens

Rotate a service-token secret

Required scopes: token.create.

Immediately invalidates the old secret and returns the replacement once. Preserves label, scopes, and expiry; does not renew an expired token (404). The caller must hold every target scope. Both authorization and If-Match are checked after the organization lock. Rotation of your own token requires storing the returned replacement before any subsequent calls. Do not retry an ambiguous response with a fresh validator; the previous response secret cannot be recovered. Idempotency-Key is unsupported and rejected with 422 idempotency_not_supported. No secret-bearing response or one-use download stream is retained.

Response headers:

  • ETag (200): Configuration validator. Excludes volatile last-use metadata, which is available in the token list only. Rotation invalidates this validator.

Authentication

AuthorizationBearer

Organization-owned service token. Issue the initial token in organization credential settings. Scopes are documented per operation via x-required-scopes; they are not OAuth scopes.

Path parameters

organization_idstringRequiredformat: "uuid"
credential_idstringRequired

Headers

If-MatchstringRequiredformat: "^"token-[a-f0-9]{64}"$"

Use the latest service-token configuration ETag unchanged. Missing: 428; stale: 412. Wildcards, lists and weak validators are rejected.

Request

This endpoint expects an object.

Response headers

X-Request-IdstringOptional
ETagstringOptionalformat: "^"token-[a-f0-9]{64}"$"

Configuration validator. Excludes volatile last-use metadata, which is available in the token list only. Rotation invalidates this validator.

Response

Successful operation
idstring
organization_idstringformat: "uuid"
labelstring
scopeslist of enums
expires_atinteger or null

Unix timestamp in seconds; null means no deadline or no recorded use.

secretstringformat: "^svc_[a-f0-9]{64}$"
Returned once. Store in a confidential backend.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error