API keys

An API key lets a program act for your company. Make one for each program, so each can be replaced or stopped on its own and the audit log says which did what.

Making one

Keys are made by an admin or owner.

1. Sign in to your company, and open API keys in the sidebar.
2. Give the key a name that says who or what will hold it: "Shop sync", "Print farm", "Dana's laptop".
3. Choose its scope, the most it may ever do (below).
4. Create key. The whole key, fdr_ and 64 characters, is shown once, on the page that follows. Copy it now. Afterwards only its first few characters are shown, enough to tell keys apart.

Give a key the least it needs. A scope can't be changed after the key is made: make a new key instead.

Keeping it safe

A key is a password for your company's data. Keep it out of your source code and out of git; put it in the environment, or in your platform's secret store, and read it from there:

export FOUDRA_URL=https://acme.foudra.com
export FOUDRA_API_KEY=fdr_…

The examples in this manual, and the tools, read those two variables.

Sending it

Every request carries the key in the Authorization header:

curl -H "Authorization: Bearer $FOUDRA_API_KEY" "$FOUDRA_URL/api/parts?per=10"

import os
import requests

api = requests.Session()
api.headers["Authorization"] = "Bearer " + os.environ["FOUDRA_API_KEY"]
base = os.environ["FOUDRA_URL"].rstrip("/")

r = api.get(f"{base}/api/parts", params={"per": 10}, timeout=30)
r.raise_for_status()
for part in r.json()["data"]:
    print(part["part_number"], part["name"])

Without a key, or with a revoked one, the answer is 401. A request the key's scope doesn't cover is 403, and the message names the scope it needed.

In whose name

What a key changes is recorded against the person who created it. Some actions also need that person to hold a role: raising a work order needs a planner, approving a purchase order an admin. A key never lends more than its creator has.

A program that acts for different people, a chat assistant say, sends X-On-Behalf-Of: dana@acme.example with a request, and the change is made in that person's name and with their role, provided both they and the key's creator hold it. See the reference for the actions this applies to.

Replacing and revoking

Revoke on the API keys page stops a key at once and for good; its next request gets 401. The key's row stays, so the audit log can still say which key did what.

To replace a key without stopping anything, make the new one, put it where the program reads it, check the program works, then revoke the old one. Do the same at once if a key may have leaked: pasted in a chat, committed to git, left on a laptop that's gone.

If the company's subscription lapses, every key gets 402 until it's paid; nothing is deleted.