Keys and Credentials

There are two separate questions, and conflating them is the usual source of confusion:

1. Who is calling? Answered by the credential on the inbound request -- an issued sk-dz- key, a DevZero access token, or your own provider credential.
2. Whose credential pays the provider? Answered by custody, resolved inside the control plane per request.

A request's payer is deliberately not derivable from its issued key, which is why the gateway stamps the arm that won onto every telemetry row.

Issued keys

The customer-facing credential for headless, CI and SDK traffic that carries no resolvable OAuth identity.

Your own provider credentials

The Provider keys screen holds your own provider credentials: the ones your traffic forwards with, and the read-only accounts your invoices are reconciled against. It has two sections -- Forwarding credentials and Reconciliation accounts -- because those are different jobs.

A credential row never contains plaintext or ciphertext. What you see is metadata plus a last-four mask, a status, when it was last tested and the error if it failed.

A team may hold several named credentials for one provider, with exactly one marked default.

BYOK: two tiers, and they are different axes

Managed custody

DevZero can provision and hold the upstream key for a team. Enrolling a team mints one key on the upstream, stores its material in DevZero's encrypted credential store, and keeps a backstop spend limit pushed upstream.

Which credential paid: the custody ladder

On a keyed request the gateway does not hold the secret. It asks the control plane at forward time, and the control plane resolves:

1. The key's explicit custody binding, if it has one. An explicit byok or managed binding that cannot resolve is denied -- never moved onto the other party's credential.
2. Otherwise auto: your own credential where the team holds one for the decided upstream, the DevZero-provisioned one otherwise.
3. As a last resort, the installation credential configured on the deployment itself. Where no credential is bound at all, unresolved custody fails closed rather than spending DevZero's account.

The arm that won is stamped on the telemetry row as byok, managed, installation, or empty when nothing was forwarded. That column is the boundary the managed-usage ledger uses to exclude customer-funded spend, and the ledger's table refuses a BYOK row outright rather than filtering one out.

DevZero access tokens

Besides an issued key, the gateway accepts a DevZero access token carrying the inference scope, verified against DevZero's published signing keys. It takes the same keyed connector route with team custody.

Arming this is deliberately environment-only and fixed at boot, both or neither: the issuer and the gateway's own audience identifier. A gateway that learned its issuer from a configuration sync would spend the window before the first tick forwarding DevZero tokens upstream as if they were provider keys.

Which shape a bearer token is, is decided on its issuer and never on "is it a JWT". A foreign issuer keeps the passthrough untouched; a token naming DevZero's issuer that fails any check is answered 401 with one generic body for every cause, and is never forwarded onward. A verified token's carrier is stripped regardless of the verdict -- it is a bearer for DevZero's own authorization server, so leaking it to a model provider would be worse than leaking a provider key.

Identity linking

The gateway observes vendor-side identities. The People screen's linking tab resolves them onto real people, so attribution names humans rather than opaque ids.

Suggestions carry the reason they were made: an exact email match, a domain match, or a name overlap. Linking can be done one at a time or in bulk, and can be undone.