# Service accounts

> Give a server application its own identity and manage its current authority.

Section: Synapse and Locus. Web page: https://docs.katara.com/products/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:

```typescript
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:

```python
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](https://docs.katara.com/products/access.txt) 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.