How-to guide For administrators

Issue an API token

Give a system or an agent its own token to read the record over /api/v1. There is no form for this in the application; it is issued from the shell.

Before you start

Shell access to the box, as the service account with its environment loaded — see Deploy.
A name for the holder — jira-intake, ci, claude-desktop — 2 to 48 characters: lower case letters, digits, dots, dashes or underscores, starting with a letter or digit.

1. Issue it:

.venv/bin/python -m dpf token create NAME --note "who holds it"

The token is printed once, as dpf_… — nothing afterwards can show it again; only its SHA-256 is kept.

2. Give it to the holder, as a bearer token:

curl -H "Authorization: Bearer dpf_…" https://<your host>/api/v1/products

3. To rotate it later: issue the replacement under a new name, move the caller to it, confirm it works, then revoke the old one.

.venv/bin/python -m dpf token create NAME-2 --note "replaces NAME"
.venv/bin/python -m dpf token revoke NAME

python -m dpf token list shows it live, with when it was last used — and so does the API page in the application, under Service tokens.

"NAME already has a live token." One name holds one live token at a time. Revoke it first, or issue the new one under another name.
401 on every call. The token was mistyped or revoked — token list says which; a revoked token stops working on its very next request.

Read API and MCP — every endpoint a token can reach. It reads only: it cannot answer a demand, accept a draft or the agreement, sign off the integration test, or approve and promote a release — there is no scope that would let it.
Rotate a secret — revoking a token that leaked.