API authentication

Every request carries an API key in the Authorization header. Keys belong to the organization, not to the person who made them: a key keeps working after its creator leaves, so when someone leaves your team, revoke the keys they created.

Create a key

1. In the console, go to Settings > API keys. Everyone in the organization can see the keys; only owners and admins can generate or revoke them.
2. Click Generate key, give it a name you'll recognize later (for example ticketing-prod), and choose when it expires: 30, 90 or 365 days, or never. Choose its scopes and, if you can, the IP addresses it may be used from (see Restrict a key).
3. Copy the key now. It is shown once. We store only a hash of it, so nobody at OpenBait can show it to you again.

A key looks like this:

ob_live_q3Zx8a1B...

After it is created, the console shows only its first characters (ob_live_q3Zx8a1B…), its name, who created it, when and from which IP address it was last used, its scopes and IP allowlist, and when it expires.

An organization can have 10 active keys. Revoked and expired keys don't count.

Send the key

curl https://openbait.com/api/v1/ext/cases \
  -H "Authorization: Bearer $OPENBAIT_API_KEY"

The header is the only place a key is read from. A request without a valid key gets 401 unauthorized. The answer is the same whether the key is missing, invalid, revoked or expired.

Restrict a key

Limit what a key can do and where it can be used from, so a key that leaks is worth less. Set both when you generate the key, or later with Edit next to it. Owners and admins can change them; a change applies from the key's next request.

IP allowlist

Add the addresses your systems call from, one per line: single addresses (203.0.113.7, 2001:db8::7) or CIDR ranges (203.0.113.0/24, 2001:db8:abcd::/48), up to 20 entries. A request from any other address gets 403 ip_not_allowed, even with a valid key.

Leave the list empty for no restriction. 0.0.0.0/0 and ::/0 are refused: an empty list already means "any address".

The list shows each key's last used time and the address it was used from. An address you don't recognize is a reason to revoke the key.

Scopes

A key needs at least one. A request to an endpoint the key has no scope for gets 403 insufficient_scope. A dashboard that only reads case status needs only cases:read, so a leak of that key can't open cases or use your takedowns. Keys created before scopes existed have both.

Rotate a key

Rotate without downtime, in this order:

1. Create a new key, with the same allowlist and scopes as the old one.
2. Switch your systems to it and deploy.
3. Revoke the old key once its Last used time stops moving.

Rotate on a schedule (set the new key to expire, for example after 90 days) and whenever someone who had the key leaves.

Revoke a key

Click Revoke next to the key. It stops working on the next request, and this can't be undone. Revoked keys stay in the list so you can see when they were revoked.

Keep keys secret

A key can open takedown cases that use your organization's monthly takedowns. Treat it like a password.

• Keep it on your servers only: in an environment variable or your secret manager.
• Never put it in a web page, a mobile app, or anything else that runs on someone else's device.
• Never commit it to a repository, and keep it out of logs and tickets.
• Use one key per system, so you can revoke one without touching the others.
• Give each key only the scopes it needs, and an IP allowlist when the system calls from fixed addresses.
• If a key may have leaked, revoke it immediately, then create a new one.