Skip to main content
A service account is a non-human user that exists only to call the Onyx API. Creating one gives you an API key, which lets you build custom applications, integrate with external systems, and automate workflows.
This page applies to Onyx v4.7 and later. For older versions, see Service Accounts before v4.7.
A service account is a distinct user in Onyx, so you can trace its activity, keep its chat sessions private, and scope resources to it.

​
How a Service Account Gets Its Access

A service account has no permissions of its own. Its access is the combination of the permissions of every group you assign it, exactly like a person’s access. Assigning several groups adds their permissions together.
If a key can chat but search returns nothing, check whether its service account is in a group.
For how groups and permissions fit together, see Understanding Permissions.

​
Who Can Manage Service Accounts

Managing service accounts requires the Manage Service Accounts permission, which an admin grants to a group. Admins always have it.
Granting Manage Service Accounts is equivalent to granting Admin. The group selector is deliberately uncapped, so anyone who can create a service account can put it in the Admin group and then use its key.

​
Creating a Service Account

1

Navigate to Service Accounts

In the Admin Panel, go to Service Accounts under Integrations.
2

Create the account

Click New Service Account, give it a name, and select the groups it should belong to. You can change both later.
3

Save and copy the key

Copy or download the key before closing the dialog. Onyx shows it only once.
On Onyx Cloud, service accounts require a paid plan. Trial workspaces cannot create API keys.

​
Managing Service Accounts

The Service Accounts page lists each account with its name, masked key, and groups. For each account you can:
Regenerating or deleting a key breaks any application still using the old one.

​
Personal Access Tokens

Service accounts are for applications. When you want a token that acts as a person, use a Personal Access Token instead. Any user with the Create User Access Token permission can create one from Settings > Accounts & Access. See Overview & Auth for token scopes and usage.