Authentication
Station keys and their scopes, OAuth for assistants, and why signing stays a person's act.
Every call carries a station key as a bearer token. There are no cookies and no sessions: a request with a valid key is complete on its own.
Authorization: Bearer rwaff_k_0123456789ab_...
Station keys
- A person with access to the station makes a key in the portal under API and MCP (/developers): a name, the stations it covers, its scopes and when it expires (never, or after 30, 90 or 365 days).
- The secret is shown once, when the key is made. Store it like a password; the portal keeps only a hash and cannot show it again.
- A key reaches only the stations it was made for, and only while the person who made it still has access to them. When their access ends, so does the key's.
- A key can be revoked on the same page at any time. It stops working on its next call.
- A key that is missing, malformed, unknown, revoked or expired answers 401
invalid_principal, the same way each time.
Scopes
| Scope | Unlocks | Also needs |
|---|---|---|
read | Every read: affiliations, weeks, versions, status, clearance, creatives, audio, exports and documents. | Nothing more. |
report | Reporting affidavits and show certificates, uploading logs and applying their matches. | The key's owner holds the report or sign role, and the affiliation is not read-only. |
acknowledge | Acknowledging a new version. | The affiliation is not read-only. |
Each endpoint page names the scope it needs. GET /v1/affiliations shows, per affiliation, what the key may do there: canReport and readOnly. A key without the scope an endpoint needs answers 403 insufficient_scope or forbidden.
People only: signing
An endpoint with no key scope is for people. Today that is one: signing a week. A signature is an attestation that the affidavits are true, and it records who signed, their title and when, so it is made by a person signed in to the portal and never by a key, a script or an assistant. POST .../sign answers 403 key_cannot_sign for every key, and over MCP the sign_week tool returns a link to the portal's signing panel instead of signing.
OAuth for assistants (MCP)
An assistant that connects to the MCP server can use a station key like any client, or a person can sign in: the assistant opens a sign-in page on the portal, the person allows it, and it receives a token of its own (OAuth with PKCE). That token acts for the person, can report where they can, cannot sign, lasts 30 days from its last use (90 days at most) and appears under API and MCP, where the person can end it. It works only on the MCP server, never on the REST API.
Keeping keys safe
- Give each system its own key with only the scopes it needs, so one can be revoked without touching the others.
- Never put a key in a web page, a browser or a public repository. Call the API from a server.
- Choose an expiry for keys held by contractors or trials, and revoke a key the moment it may have leaked.