Create a service account and its API tokens Enterprise¶
A nightly cost export, a script that onboards a team, a CI job that issues keys: each should have its own account, not a person's password. A service account has its own tokens, its own roles and its own owners, and everything it does is in the audit log under its name. When the person who built it leaves, it keeps working.
Service accounts are part of the Enterprise edition; what Enterprise includes depends on the features your licence includes. On the Community edition, a person's personal access token is the way to script Vidai.
Tokens are not keys
A service account's tokens manage Vidai (people, keys, rules, settings). They never call models: programs call models through the gateway with a key. A service account holds no keys.
Before you start¶
- Organisation admins create service accounts anywhere; group admins in the teams they run.
- Giving a service account a role always waits for a second admin.
Steps¶
Create the account¶
- Open Service accounts and choose New service account.
- Give it a Name, and choose where it Belongs to: the whole organisation (organisation admins only) or a team.
- Optionally say What it's for and Who to ask about it.
- Choose Create service account. It starts with no tokens and no roles.
Give it a role¶
- Open it, choose Roles, then Give a role: group admin of a team, or (organisation admins only) organisation viewer or organisation admin. Optionally Until a date.
- Confirm. It shows Waiting for a second admin until another admin approves it in Approvals.
Without a role, its tokens can read what any signed-in person can and change nothing.
Make a token¶
- Open its Tokens tab and choose New token.
- Name the token after where it's used. Choose What it may do; choose nothing and it may do everything the service account may do. Choose how long it Lasts: a year at most.
- Choose Make token, copy it and put it where that system keeps secrets. It's shown only now; afterwards only its first characters are shown.
Check it worked¶
The account lists its token, what it may do, when it expires and when it was last used. Roles & access lists its role once approved. Its actions appear in the audit log under its name.
Look after it¶
- Revoke on a token stops whatever uses it at once.
- Disable revokes every token at once; enabling it again doesn't bring them back: make new ones.
- Delete ends its tokens and roles; what it did stays in the audit log. This can't be undone.
- Owners (its own tab) change it, look after its tokens and give it roles.
Good to know¶
- A token can never do more than its account.
- Service accounts and API tokens never use single sign-on.
- If your licence stops including service accounts, their tokens stop working but the accounts and roles stay; licensing again brings them back.
- Service accounts count towards your licence's limits where it sets one.
Related¶
- Review and revoke API tokens
- Create a personal access token
- Give someone a role
- Concept: Service accounts and API tokens
- Keys and tokens: which one a program needs