# Keys Throughline keeps two separate shelves of credentials. They look similar — both live under a production's Settings — but they do opposite jobs, and mixing them up is the mistake this page exists to prevent. ## Your provider keys **Your provider keys** are the model and API credentials a production supplies for its own AI usage — an image-generation provider, a language model provider, whatever the production has an account with. Bring your own key, and Throughline uses it on the production's behalf for the AI features that need one. Provider keys are **write-only**. Once saved, the credential itself is never returned — not to the admin who entered it, not to crew, not over the API. Throughline shows only a label, a last-4 stub, and who set it and when, so you can confirm a key is in place without anyone ever reading the value back out. The full credential exists in exactly one place: encrypted at rest, decrypted only at the moment Throughline uses it on the production's behalf. Provider keys are never exposed to crew. A department head using a feature that calls out to a provider never sees, needs, or can retrieve the underlying credential — the production's admin manages it once, centrally. ## Throughline access keys **Throughline access keys** are the keys Throughline itself issues for something else to reach *in* — what you send as `Authorization: Bearer tl_...` against the [REST API](api.html) or the [MCP server](mcp.html), both of which read the same key the same way. A production's admin mints one from Settings, gives it a label describing what it's for, and picks its scopes. The full token is shown exactly once, at creation; after that Throughline keeps only a recognizable prefix, the same way a provider key's plaintext is never retained. ### Scopes | Scope | Grants | |---|---| | `read` | The production-wide read surface | | `write` | The production-wide write surface | | `submit:turnover` | Submitting work back on a delivery | | `read:money` | A vendor's own purchase orders and cost-report line | A key can hold any combination. `read`/`write` are the default when a key is minted with no scopes named; `submit:turnover` and `read:money` are never on by default, and only mean anything on an engagement-bound key — see below. ### Two shapes **Production-wide** is the ordinary shape: it reads and writes across the whole production, scoped only by `read`/`write`. This is what you get unless you ask for the other kind. **Engagement-bound** is minted for one vendor organization's own automation — an admin names which of the production's open vendor engagements the key belongs to when they mint it. An engagement-bound key: - reaches **only** the [bundle, turnover, media and purchase-order surface](api.html#one-round-trip-clamped-to-the-caller) of the API — every other endpoint refuses it outright, regardless of which scopes it holds; - on that surface, is clamped to exactly what its engagement has been granted, and nothing else — the identical reach a person signed in *as* that vendor's own seat would get, computed the same way. A vendor's own automation and a vendor's own crew member see the same slice of the production, by the same rule, whichever door they come through. A vendor organization's *people* reach Throughline a different way — signing in on a seat, the same as any other crew member, scoped to their engagement. This page is about the credential a vendor's *automation* uses instead; a seat is provisioned separately and isn't a key at all. ### Scoping and revocation - **One key, one production.** An access key is bound to the production it was minted on. There is no key that reaches across productions. - **Scopes, not roles.** Each scope is independent, and an endpoint that needs one refuses a key without it outright rather than degrading silently. - **Revocation is immediate.** Revoking a key from Settings takes effect on the very next request — REST or MCP — with no propagation delay to account for. ### What an access key can't do An access key authenticates as the production (or, engagement-bound, as one vendor's engagement on it) — never as a specific crew member's session. It can read and write within the scopes it holds, but it never gains a person's own permissions, never sees another production, and carries none of the write access a signed-in person has outside the [documented write endpoints](api.html#write-endpoints). ### Usage Every authenticated request is counted, per key, per day. Settings shows each key alongside its request count and when it was last used — so an admin managing a production's keys can tell which ones are actually in use without asking around, and see a dead integration before it's ever mentioned. Nothing here is gated or billed: no request is refused for volume today. The counters are the plumbing a future pricing decision would read, not a limit this pilot enforces. ## Which one do I need? - Wiring up a model provider so the production's assistant or generation tools can use it → **Your provider keys**. - Building or connecting a tool that reads or writes production data over the API or MCP → **Throughline access keys**, production-wide. - A vendor organization's own pipeline reading or submitting work on its own engagement → **Throughline access keys**, engagement-bound — ask your Throughline contact to have one minted against your engagement.