Skip to main content
Service Account Tokens

Create a Service Account Token for an Identity

Exchange a Service Account Key for a short-lived access token bound to a specified Identity.
POST /api/v1/forward/identities/{identity_id}/service_account_tokens Issue a Service Account Token that represents a specified end user (Identity). The caller uses the token to access Forward APIs in that Identity's context, such as creating a Session or querying the Identity's configuration. This is suitable for issuing a token to a single end-user session in an enterprise product. To manage enterprise resources such as Templates and Identities, use Create a Service Account Token, which issues a token with an administrator subject.

Request headers

HeaderRequiredDescription
AuthorizationYesBearer <Service Account Key>
Content-TypeYesapplication/json

Path parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.

Request body

ParameterTypeRequiredDescription
ttl_secondsintegerNoToken lifetime in seconds, from 1 to 43200 (12 hours maximum). The platform default is used when omitted.
metadataobjectNoBusiness metadata that identifies the token's purpose for auditing.

Example request

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

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": "8c1d4e7f-2a5b-4c8d-b3e6-9f0a1b2c3d4e",
  "service_account_id": "sa_019f000000",
  "credential_id": "sak_019f000000",
  "subject_type": "identity",
  "identity_id": "idn_019eabc123"
}

Response fields

FieldTypeDescription
typestringAlways service_account_token.
access_tokenstringShort-lived access token. It is returned only in this response; store it securely.
token_typestringAlways Bearer.
expires_inintegerLifetime in seconds.
expires_atstringExpiration time in RFC 3339 format.
auth_token_idstringUnique token identifier used to revoke the token.
service_account_idstringID of the Service Account that issued the token.
credential_idstringID of the Service Account Key that issued the token.
subject_typestringToken subject type. This endpoint returns identity.
identity_idstringID of the Identity bound to the token.

Errors

HTTPTypeCodeCondition
400invalid_request_error-identity_id is empty, the request body is invalid, or ttl_seconds is outside 1–43200.
401authentication_error-The Service Account Key is invalid or expired, or another credential type was used.
403permission_error-The target Identity is disabled.
404not_found_error-The target Identity does not exist.
503api_error-The token issuance service is temporarily unavailable. Try again later.

Notes

  • The token is bound to the Identity. Its holder can act only as that Identity and cannot operate on another Identity's data.
  • Business requests using the token are rejected after the Identity is disabled or deleted.
  • Issue one token per end-user session and choose a ttl_seconds value that matches the session duration.

Create a Service Account Token

Revoke a Service Account Token

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Create a Service Account Token for an Identity - Qoder