Service Accounts¶

A service account is a principal for a machine, not for a person. A CI pipeline, a script, or an Imbi service uses a service account to call the Imbi API.

Like a user, a service account gets permissions from its role in each organization that it is a member of. A service account without a membership has no permissions. A service account is never a platform administrator.

A service account authenticates with one of two credentials:

To manage service accounts, open Admin > Global Admin > Service Accounts. The Admin item shows only for platform administrators.

Permissions¶

service_account:update also covers the memberships, the API keys, and the client credentials of a service account. The service account routes are not organization routes. They use the union of your roles in all your organizations. See Permissions across organizations.

Create a service account¶

1. Open Admin > Global Admin > Service Accounts.
2. Click New Service Account.
3. Enter the fields in the table below.
4. Click Create Service Account.

A new service account has no credentials. Add an API key or a client credential after you create the account.

Organization memberships¶

A service account can be a member of many organizations, with one role in each.

1. Open the service account.
2. Under Organization Memberships, click Add to Organization.
3. Select the organization and the role.

To change a role, select a different role in the row of the organization. To remove a membership, click the remove button in the row.

API keys¶

1. Open the service account.
2. Under API Keys, click Create API Key.
3. Enter a Key name, for example production.
4. Click Create.
5. Copy the key from the API Key Created dialog. Imbi shows the key one time only. Imbi stores only a hash of the secret.

The key has the form ik_<key id>_<secret>. Send it as a bearer token:

curl --fail -H "Authorization: Bearer ik_..." https://imbi.example.com/api/organizations/

The dialog creates a key with no scopes and no expiry. The API (POST /service-accounts/{slug}/api-keys) also accepts these fields:

Each row in the key list has two actions:

• Rotate API key makes a new secret for the same key id. The old secret stops working. Imbi shows the new key one time only.
• Revoke API key stops the key. Imbi keeps the revoked key in the list for audit.

A rotated or revoked key stops at once.

Client credentials¶

1. Open the service account.
2. Under Client Credentials, click Create Credential.
3. Enter the fields in the table below.
4. Click Create.
5. Copy the client id and the client secret. Imbi shows the secret one time only.

The client id has the form cc_<random>. To get an access token, send a form-encoded request to POST /auth/token under the API prefix:

curl --fail -X POST https://imbi.example.com/api/auth/token \
  -d grant_type=client_credentials \
  -d client_id=cc_... \
  -d client_secret=...

The response has an access token and a refresh token. The lifetimes are the same as for users. See Tokens. Send the access token as Authorization: Bearer <token>. To get a new pair, send the refresh token with grant_type=refresh_token.

You can send scope (permission names, separated by spaces) in the token request. If the credential has scopes, the token gets the scopes that are in both lists. Imbi writes the granted scopes into the token, and a token refreshed from it keeps them. The token gets only the permissions that are both in its scopes and in the roles of the account. A token with no scopes gets all the permissions of the roles, as an API key with no scopes does.

Rotate credential and Revoke credential work like the actions for API keys.

Delete or disable a service account¶

To stop an account without deleting it, open it, turn off Account active, and save. Imbi then refuses its API keys, its client credentials, and its tokens.

To delete an account:

1. Open the service account.
2. Under Danger zone, click Delete account.
3. Confirm.

Imbi deletes the account, its API keys, and its client credentials. If the account is the credential of a runner pool, Imbi refuses the delete with 409 service_account_in_use. Change the pool first. See Agent Runners.

Agent service accounts¶

Imbi makes a service account for each agent when you create the agent. The agent acts as this account when it calls the Imbi API. See Agents.

A membership with no role gives no permissions. To let an agent use the Imbi API tools, give its service account a role in the organization of the agent (see Organization memberships). The Organization Memberships card shows such a membership as No role, and the API returns its role as null.

Keep the agent's service account in one organization only. If it is a member of more than one organization, Imbi gives the agent no API token (service_account_in_other_organizations). See Agent Runners.

When you delete the agent, Imbi deletes its service account and the credentials of that account.

Imbi service accounts¶

Five Imbi services call imbi-api as their own service account:

The assistant and the Slack bot use their accounts only to get the token of their AI provider (workload identity). For tool calls, they send the token of the caller to imbi-api. imbi-mcp has no service account.

imbi-api setup creates the accounts in the organization that it creates. For an install that already exists, or for another organization, run this command:

imbi-api setup-service-accounts --organization <organization slug>

Run imbi-api setup-permissions first, because the command gives each account the seeded role of the same name. When only one organization exists, you can omit --organization.

For each credential, the command does one of these:

The command does not change the role of an account that already has a membership in the organization. It does not change Account active.

For the extra setup of imbi-workflows, see Workflows.

Related pages¶

• Roles and Permissions
• Users, Teams, and Organizations
• Authentication
• Security model