Create a Service Account Token

Exchange a Service Account Key for a short-lived access token with an administrator subject.

POST /api/v1/forward/service_account_tokens A Service Account Token is a short-lived credential for calling Forward APIs in enterprise integrations. Use the enterprise Service Account Key to call this endpoint and obtain a token with an administrator subject. Send the token as a bearer token in the Authorization header when accessing management APIs such as Templates, Identities, and Sessions. To access session APIs as a specific end user (Identity), use Create a Service Account Token for an Identity.

Request headers

Header	Required	Description
Authorization	Yes	`Bearer <Service Account Key>`
Content-Type	Yes	`application/json`

Request body

Parameter	Type	Required	Description
ttl_seconds	integer	No	Token lifetime in seconds, from 1 to 43200 (12 hours maximum). The platform default is used when omitted.
metadata	object	No	Business metadata that identifies the token's purpose for auditing.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/service_account_tokens' \
  -H "Authorization: Bearer $QODER_SA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ttl_seconds": 3600,
  "metadata": {
    "purpose": "admin automation"
  }
}'

Example response

HTTP 201 Created

{
  "type": "service_account_token",
  "access_token": "sat-example-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-08-06T12:00:00Z",
  "auth_token_id": "3f8a2b1c-6d4e-4f2a-9b7c-1e5d8a0c4b2f",
  "service_account_id": "sa_019f000000",
  "credential_id": "sak_019f000000",
  "subject_type": "admin"
}

Response fields

Field	Type	Description
type	string	Always `service_account_token`.
access_token	string	Short-lived access token. It is returned only in this response; store it securely.
token_type	string	Always `Bearer`.
expires_in	integer	Lifetime in seconds.
expires_at	string	Expiration time in RFC 3339 format.
auth_token_id	string	Unique token identifier used to revoke the token.
service_account_id	string	ID of the Service Account that issued the token.
credential_id	string	ID of the Service Account Key that issued the token.
subject_type	string	Token subject type. This endpoint returns `admin`.

Errors

HTTP	Type	Code	Condition
400	`invalid_request_error`	-	Invalid request body, or `ttl_seconds` is outside 1–43200.
401	`authentication_error`	-	The Service Account Key is invalid or expired, or another credential type was used.
503	`api_error`	-	The token issuance service is temporarily unavailable. Try again later.

Notes

Create and manage Service Account Keys on the Enterprise credentials page in the Qoder console. They are available only to enterprise organizations.
A token expires automatically and cannot be renewed. Obtain a new token before the current one expires.
Do not use the Service Account Key directly with business APIs. Business APIs accept only a PAT or Service Account Token.

​Request headers

​Request body

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related APIs