Service accounts & tokens
Authenticate a script or integration without a person's login. A service account is a machine user in a workspace. An API token is its scoped, revocable key.
When a script, a CI job, or a backend service calls the Chronicler API, it should not use a person's login. It should have its own identity. Chronicler gives you two things for this: a service account and an API token.
A service account is a machine user
A service account is a user of a machine kind, owned by a workspace. It cannot sign in with a password or a provider, and it holds roles of its own, exactly like a person does. You give it the roles it needs and nothing more, so a script that only reads never gains the ability to write.
Because it is a real principal, everything a service account does is attributed to it in the audit trail. You can always tell an automated action from a person's.
An API token authenticates the call
An API token is the credential a service account, or a person, uses on a request. It is sent as a bearer token, the same as any other:
Authorization: Bearer chr_sat_6311hvq3sgvd7vsmyxtmsh0sas...
A token is shown once, at creation. Copy it then. Chronicler stores only a hash, so it can never show you the value again.
Copy the token now
The full token is displayed a single time. Store it in your secret manager before you close the dialog. If you lose it, revoke it and create a new one.
Scope: the intersection of roles and grants
A token does not carry unlimited power. Its effective permission is the intersection of two things: the live roles of its owner, and the token's own scope. Narrowing either one narrows what the token can do, and the token can never exceed its owner's roles.
- Revoke a role from the owner, and every token loses that ability at once.
- Give a token a read-only scope, and it cannot write even if the owner can.
A token is bound to one workspace. It cannot reach across into another.
What a token can never do
Some capabilities are on a deny-list and are off-limits to any API token, no matter its scope. A token never acts as an administrator, and it can never exercise a denied securable. This keeps a leaked key from becoming a full account takeover. The OpenAPI spec marks which operations a token may call, derived from that deny-list, so you can see at a glance what is reachable.
Create and revoke
Create a service account from Workspace settings, then Service accounts, give it roles, and issue a token. A personal API token, for your own automation, is created from your account settings and is gated behind step-up authorisation.
Revoking a token stops it immediately. Revoking is the right response to a leak, and it does not affect the service account's other tokens.
Where to go next
- The header and the token pair are covered in Authentication.
- See the design in Authentication & identity.