Service accounts and API keys

A script or integration that talks to UnitX needs an identity and a credential. A service account is a non-human member of your organization that holds a role, just like a colleague; an API key is the secret a program presents. Keeping integrations on service accounts means they do not stop working when a person leaves, and can be switched off in one move.

Key concepts#

Service account

A non-human member for one integration or script. It belongs to the organization, not to whoever created it.

API key

A secret beginning uxk_, sent with each request. A key belongs either to a person or to a service account, never both.

Scopes

The permission keys an API key may use. A request needing a permission outside them is refused.

Why use a service account#

An integration running under a person’s account inherits everything that person can do, and breaks the day they are suspended or leave. A service account has its own role, so what the integration can do is visible on the Roles screen in the same words as for a colleague — and a service account’s key can only use what both its scopes and its role allow. An over-scoped key on a service account with the Viewer role still cannot change anything.

Who can manage them#

Create a service account#

1. Open the tab

   Go to SettingsService accounts.

2. Name it after what it does

   Enter a Name such as “Nightly invoice sync”. Names must be unique in the organization.

3. Choose a role

   Pick the narrowest role that lets the integration do its job. Create a custom role if none fits — see Roles and permissions.

4. Choose Create

   The account appears in the list as Active.

Manage a service account#

Each row shows the account’s name and status, how many API keys it holds, and when it was last used.

• Change its role with the role picker on the row. The new role applies to the next request any of its keys makes.
• Disable it to stop the integration at once (see below).
• Enable a disabled account to let it be used again.

Disable an integration immediately#

Choose Disable. Every API key the account holds is revoked in the same moment, and the confirmation says how many — for example Disabled — 2 API key(s) revoked. This is the move to make when an integration is misbehaving or a key may have leaked.

API keys#

API keys are created and revoked through the UnitX API rather than on a settings screen. Someone with api_key.create creates a key by giving it:

Name

Between 2 and 100 characters, so you can tell keys apart.

Scopes

At least one permission key, such as project.view. Any key UnitX does not recognise is rejected rather than ignored.

Expiry

Optional. A date and time after which the key stops working.

The secret is returned once, when the key is created, and cannot be read again. Store it in your integration’s secret store straight away. The key list shows each key’s name, scopes, expiry, the first characters of the secret and when it was last used. Revoking a key stops it immediately.

How to send a key, rate limits and error formats are covered in API overview.

What happens to a person’s keys#

• Suspending or removing a member revokes every API key they created in this organization. Reactivating them does not restore those keys.
• Service accounts a person created are not affected when that person leaves, because they belong to the organization.
• Keys are not subject to the organization’s two-factor requirement; their protection is their scopes and, for service accounts, their role.

Best practices#

• One service account per integration, so disabling one never takes down another.
• Give each key only the scopes the integration uses, and set an expiry where you can.
• Check “last used” regularly. An account or key that has not been used for months is a credential worth revoking.
• Scoped permissions (such as “Their own records”) do not work for machine credentials — a scope describes a person. Give a service account’s role the unscoped permission instead.

Related pages#

• API overview
• OAuth applications
• Roles and permissions