Keys & principals

A call always acts as exactly one principal: a person or a service account. The key can never do more than that principal.

Two kinds of principals

	Personal key	Service account key
Prefix	`bodo_uk_live_` · `bodo_uk_test_`	`bodo_sa_live_` · `bodo_sa_test_`
Acts as	the person, under their AI mandate	the service account with its own roles
Valid while	the person is a member and not blocked	the service account is active
Lifetime	at most 90 days, default 30	at most 366 days, default 90
Meant for	your own scripts and tools	production integrations

Personal keys need two approvals: the right to create own keys and the organization’s switch “Personal keys allowed”. test exists only in the sandbox, live only in the production organization.

How a key is built

Text

bodo_ sa _ live _ <kid, 31 chars> _ <secret, 32> <checksum, 6>

kid       public, shortened in Bodo as …Kx9a
secret    shown exactly once
checksum  catches typos before a call leaves your machine

The key travels only in the header Authorization: Bearer …. In a query or a cookie it is rejected.
Bodo stores only a hash. A lost secret cannot be shown again, only replaced.
Secret scanning: when a key shows up in public, Bodo revokes it at once and tells you by email, bell and record history.

Lifecycle

1. Create
You see the secret exactly once. At most 25 active keys per principal, none without expiry.
2. Active
Bodo warns by email and bell 14 and 3 days before the expiry.
3. Rotate
The new key works at once, the old one keeps working for up to 7 days as planned (default 24 h), not at all when you suspect misuse.
4. Paused
After a long idle time or a used-up delete budget. A warning comes 7 days before; re-enable with one click.
5. Revoked
By hand or by secret scanning, at once and for good. After 60 seconds at the latest every path rejects it.

When a key does not work

Unknown, expired, revoked, paused or from a foreign IP: the API always answers the same 401 UNAUTHENTICATED, without a reason. As the owner you see the exact reason in the request log under Settings › Interfaces › API keys. Which rights a key has: Permissions & scopes.