8. Service Accounts

Non-interactive identities with their own roles and API keys, for automation that should not authenticate as a specific human tenant user.

Endpoint Summary

GET /api/v1/service-accounts

List service accounts

Return the service accounts of the caller’s own tenant, newest first.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, ServiceAccountListResponse)

POST /api/v1/service-accounts

Create a service account

Create a non-interactive principal in your own tenant. It holds no password and cannot sign in; it acts only through the keys you issue it, and only within the roles you bind to it. A new account starts with no roles, so it can do nothing until you grant some.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: ServiceAccountCreateRequest

Request to create a service account.

Example

{
   "display_name" : "Nightly CI",
   "name" : "ci-nightly"
}

Responses

Response Body (201, ServiceAccountResponse)

GET /api/v1/service-accounts/{service_account_id}

Get a service account

Return one service account of the caller’s own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ServiceAccountResponse)

PATCH /api/v1/service-accounts/{service_account_id}

Update a service account

Apply a partial update. The name is fixed at creation: it is how the account is recognised wherever it appears, and a rename would leave every earlier record naming something that no longer exists.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: ServiceAccountUpdateRequest

Request to update a service account. Only the fields present are applied.

Example

{
   "description" : "Nightly backup runner"
}

Responses

Response Body (200, ServiceAccountResponse)

DELETE /api/v1/service-accounts/{service_account_id}

Delete a service account

Delete the account, every key it holds and every role bound to it. The keys stop authenticating on the next request. Repeating the call finishes an interrupted delete.

A protected account cannot be deleted through the API, and the request is refused with 409.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

GET /api/v1/service-accounts/{service_account_id}/roles

List service account roles

Return the roles bound to the account. Every key it holds resolves exactly these.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, RolesResponse)

PATCH /api/v1/service-accounts/{service_account_id}/roles

Set service account roles

Replace the roles bound to the account. Every key it holds resolves the new set from the next request onwards, whenever it was issued. An empty list leaves the account with no permissions at all, which is how it is switched off without destroying anything.

The roles of a protected account cannot be changed through the API, and the request is refused with 409.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: SetRolesRequest

Request payload for replacing the full role set of a Tenant User.

Responses

Response Body (200, RolesResponse)

GET /api/v1/service-accounts/{service_account_id}/tokens

List service account keys

Return the keys the account holds, newest first. Carries no secret - a key is unrecoverable after issuance. Revoked and expired keys stay listed.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ApiTokenListResponse)

POST /api/v1/service-accounts/{service_account_id}/tokens

Issue a service account key

Issue a long-lived credential that authenticates as the service account. It resolves whatever roles the account holds at the time of each request - every key of one account carries the same permissions, whenever it was issued.

The key is returned once, in this response, and cannot be retrieved again.

Requires an interactive session: a key cannot issue another, and a tenant switch cannot leave one behind.

Refused with 409 for an account the platform provisions (the S3 gateway, the node programs): its credentials are issued by its own key-possession exchange.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: ApiTokenCreateRequest

Request to issue a long-lived API token for the caller.

Example

{
   "description" : "Nightly backup runner",
   "expires_in_days" : 90,
   "name" : "nightly-backup@ci-runner-04"
}

Responses

Response Body (201, ApiTokenCreatedResponse)

DELETE /api/v1/service-accounts/{service_account_id}/tokens/{token_id}

Revoke a service account key

Revoke one key. It stops authenticating on the next request. The record is kept as a tombstone, so a client still presenting it is told the key was revoked rather than that it never existed.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses