Service account API reference

Service account endpoints

All service account management endpoints are under /api/v1/service_accounts. Project scoping is enforced through the project_id field in the request body (for creation) and visibility filters (for listing).

Create request body

{
  "name": "CI Pipeline",
  "description": "Service account for Jenkins CI integration",
  "project_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
}

Labels are not accepted in the create request. To add labels to a service account, use the PATCH endpoint after creation.

Create response body

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "CI Pipeline",
  "description": "Service account for Jenkins CI integration",
  "status": "active",
  "project_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "last_authenticated_at": null,
  "created_by": "12345678-abcd-efab-cdef-1234567890ab",
  "created_at": "2026-07-02T14:30:00Z",
  "updated_at": "2026-07-02T14:30:00Z",
  "labels": {}
}

The create response does not include credentials. To generate a client ID and client secret, create a credential as a separate step. For more information, see Create a service account.

Credential endpoints

Credentials are sub-resources of service accounts. Each service account can have up to 10 credentials.

Credential create request body

{
  "credential_type": "client_credentials",
  "expires_at": "2027-01-02T14:31:00Z"
}

Credential create response body

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "service_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "credential_type": "client_credentials",
  "identifier": "nx_sa_7kx9m2p4q1w3n5v8",
  "client_secret": "generated-plaintext-secret",
  "status": "active",
  "grace_period_seconds": 3600,
  "expires_at": "2026-12-29T14:31:00Z",
  "old_secret_valid_until": null,
  "last_used_at": null,
  "created_by": "12345678-abcd-efab-cdef-1234567890ab",
  "created_at": "2026-07-02T14:31:00Z"
}

Grace period behavior

When you rotate a credential's secret, both the old and new secrets are accepted during a configurable grace period. This prevents downtime when multiple consumers need time to update their credentials.

The default grace period is 3600 seconds (1 hour). You can override the grace period per rotation by including grace_period_seconds in the rotate request body. This field accepts values from 0 to 86400 seconds (24 hours). Setting the grace period to 0 means the old secret is rejected immediately after rotation.

Token endpoint

Token request

The token endpoint accepts application/x-www-form-urlencoded requests with the following parameters:

Alternatively, you can provide the client_id and client_secret by using HTTP Basic authentication (RFC 6749 section 2.3.1). Encode the credentials as client_id:client_secret in Base64 and pass them in the Authorization header.

Token response

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Im5leHVzLTEifQ...",
  "token_type": "Bearer",
  "expires_in": 900
}

No refresh token is issued. When the access token expires, request a new one by repeating the client credentials grant flow.

ServiceAccount fields

ServiceAccountStatus values

ServiceAccountCredential fields

Access token JWT claims

Service account access tokens include the following claims:

Error responses

All error responses use the application/problem+json format (RFC 9457).

Token endpoint errors

Management endpoint errors