---
title: "Keys & principals"
description: "A call always acts as exactly one principal: a person or a service account. The key can never do more than that principal."
lang: en
url: https://developers.bodo-app.com/en/guides/keys/
apiVersion: 2026-11-01
---

# 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](/en/problems/UNAUTHENTICATED/), without a reason. As the owner you see the exact reason in the request log under [Settings › Interfaces › API keys](https://bodo-app.com/settings/api-keys). Which rights a key has: [Permissions & scopes](/en/guides/scopes/).