Service accounts

A service account gives a server application an identity within one organization. It does not sign in as a person. A signed-in administrator creates and manages it; the application uses a separately issued, environment-scoped API key.

Create and inspect an account

Use createServiceAccount(orgID, name, requestKey, permissionRole) in TypeScript or create_service_account(org_id, name, request_key, permission_role) in Python. Names contain 1–120 characters after trimming whitespace. The role is optional; an account created without one is a builder. Save the returned operation’s resource_id as the service-account ID. Creation returns an operation receipt, not a key secret.

Read listServiceAccounts / list_service_accounts to inspect the current name, permission_role, permissions, active flag and authority_epoch. permissions is everything the role allows, and so everything a key for the account can hold. Pages accept a limit of 1–100; pass next_cursor back as after until it is absent. Select by the exact returned ID, since names are not unique identifiers.

The list requires current organization read access. Creation and changes require current service-account administration permission. Use a human application session for administration. Appropriately scoped API keys can also use these routes when their current role permits it; organization administration rejects resource-restricted keys.

Change authority deliberately

Supported roles are admin, builder, operator, reviewer and viewer. A service account cannot be an organization owner or replace a person in a human-only approval. Choose the smallest role and key scopes the application needs.

A change sends the complete name, role and active state, together with the exact authority_epoch you just read. The server advances the epoch on every accepted change, including a rename. A stale epoch conflicts; reload and review the new state before submitting a different change with a new request key.

For example, after selecting account from the current organization directory, review this request before disabling it:

const change = {
  name: account.name,
  permission_role: account.permission_role,
  active: false,
  authority_epoch: account.authority_epoch,
};
const receipt = await client.changeServiceAccount(
  orgID, account.id, change, requestKey,
);

The equivalent Python call passes the fields separately:

receipt = client.change_service_account(
    org_id, account['id'], account['name'], account['permission_role'],
    False, account['authority_epoch'], request_key,
)

Disabling an account or changing its role revokes its existing keys in the same operation. Reactivating it does not restore those keys. Issue a new key only after reviewing its current authority. Changing the name alone also advances the epoch, but does not use the role-change rule to revoke keys.

Issue a scoped key and recover safely

Set service_account_id to the exact account ID when issuing a key. Select the organization, Test or Live environment, expiry and explicit scopes. Key authority cannot exceed the account’s current role: a key asking for a permission outside it is refused with permission_denied, and the message names the role and the permission. Service-account keys can start managed runs when their permissions, grants and funding allow it; they cannot use direct Cortex billing. See Access and API keys for credential modes.

Keep the key secret in the application’s secret store. It is revealed only at issuance, and retrying issuance does not reveal it again. Never place it in a browser bundle, operation history or recovery record.

If create or change returns no confirmed response, retain the exact reviewed request and original idempotency key. After restoring the same administrator’s session, explicitly retry that identical request. Do not substitute a new epoch, role or account under the old key. A changed request requires a new review and key. Then reload the directory to inspect the resulting account state.