Service accounts and API tokens
API tokens let scripts and tools call the Orbit API. Personal tokens act as you. Service accounts give a team a non-human identity.
Personal API tokens
Section titled “Personal API tokens”Create a token from your profile. A token has:
| Property | Value |
|---|---|
| Name | 1 to 80 characters |
| Scope | read (GET requests only) or write |
| Projects | Optional. A read token can be limited to projects you can open. |
| Lifetime | 1 to 365 days, 90 by default |
The token starts with opt_ followed by 64 hex digits and is shown only once, when you create it. The list never shows a secret again. A person can hold up to 25 active tokens. Each token may make 600 requests a minute.
curl -H "Authorization: Bearer opt_..." \ https://acme.orbit.inortix.com/api/v1/auth/meA token acts as its owner, without site administration. A read token can only GET. A project-limited token reads only those projects’ routes. No token can create or list tokens: that needs a signed-in session. See API authentication for the error codes.
You can revoke your own token at any time. Site administrators can list every active token on the site, with its owner, and revoke any of them. Creating and revoking tokens is audited.
Service accounts
Section titled “Service accounts”A service account belongs to one site. It never signs in, never administers the site, and is owned by people. Use it for integrations that should outlive a person’s account.
- Site administrators create a service account with a name (1 to 120 characters) and a role, member or viewer. The creator becomes an owner.
- The owners and site administrators issue the account’s API tokens, with the same properties as personal tokens.
- Suspending the account, or losing its last owner, stops every one of its tokens on the next request (
service_account_inactive). - When the last eligible owner is removed or demoted below member, or the account is suspended, it becomes orphaned, and its tokens and agent grants on the site are revoked. Reactivating makes the caller an owner.
Use in automation
Section titled “Use in automation”An automation rule can run as a service account, so its effects are made with that account’s permissions. Only the account’s owners and site administrators may save or publish such a rule. A suspended or ownerless account makes manual runs fail with automation_actor_unavailable.