Keys and credentials: scopes, rotation and who pays
Issue runtime, service and management keys, rotate one with a grace window through the management API, set custody so the right account pays, and read key spend.
16 min readLast reviewed October 19, 2026Verified against gateway contract 0.6.0 and chart 0.10.0
What you’ll have at the end
By the end you will have three issued keys that each do one job, a rotation you can run from CI without an outage, and two teams paying two different provider accounts through the same gateway. You will also know how to read what any single key has spent.
Before you begin
- A Nautili team where you are a team admin. Issuing a management key and connecting a provider credential both need admin rights.
- Access to the Nautili dashboard. Two screens matter here: API keys under Access and Provider keys.
- For the management API steps, a self-hosted gateway you can set environment variables on. The hosted Shared Gateway refuses to serve the management API, so key lifecycle there is dashboard-only.
curlandjq. The Python and TypeScript tabs userequestsand the built-infetch.
Two questions get conflated whenever keys come up:
- Who is calling? Answered by the inbound credential, an
sk-dz-key. - Whose credential pays the provider? Answered by the key's custody, resolved per request by the control plane. The payer is deliberately not derivable from the key, so every telemetry row carries the custody arm that won.
Steps 1 to 5 answer the first question. Step 6 answers the second.
Step 1: Issue three keys in the dashboard
Open API keys and click Advanced; the Issue sk-dz key dialog opens (New Key opens the short New API key form: Name, Expiration, an optional credit limit and Custody limited to Managed or BYOK; Kind, Owner, Forward credential, Scopes and Auto custody exist only on the Advanced form). The form has Name, Kind, Owner, Forward credential, Custody and Expires, plus Scopes when the kind is management. Issue these three:
| Name | Kind | Owner | Custody | Scopes | What it can do |
|---|---|---|---|---|---|
alice-laptop | KindRuntime | OwnerAlice | Custodyleave unset (Auto) | Scopesn/a | What it can doInference only. Governed by Alice's guardrail and shares her budget bucket. Disabled automatically if Alice is offboarded. |
ci-deploy | KindRuntime | Ownernone (service key) | Custodyleave unset (Auto) | Scopesn/a | What it can doInference only. Governed by the team default guardrail, or by a guardrail bound to the key itself. Has its own budget bucket keyed on the key id. |
ops-automation | KindManagement | Ownernone | Custodyn/a | Scopeskeys:read, keys:write, usage:read | What it can doManagement API only. Can list, create, update, rotate and revoke runtime keys and read spend. Cannot read the model catalog and cannot run inference. |
Every key is sk-dz- followed by 43 base62 characters. The plaintext appears once, on the reveal after you click Issue key. Copy it then; every later read returns metadata plus a hint of the first and last characters.

Facts about the form that are easy to miss:
- Kind is immutable after issue.
- Leaving every scope unchecked grants all four (
keys:read,keys:write,usage:read,models:read). - A management key is ownerless, admin-issued, and refused on every inference route.
- Expires is optional. Unset means never.
- Custody offers Auto, Managed and BYOK. Auto is the default and the table shows it as Legacy. Step 6 covers the difference.
Step 2: Enable the management API on your gateway
The management API is dormant until you switch it on. Set three variables on the gateway deployment and restart it.
On the Helm chart, AUTH_TOKEN and GOVERNANCE_ISSUED_KEYS=true are already rendered from config.authToken and governance.enabled: true; add only MGMT_API_ENABLED through config.extraEnv: [{name: MGMT_API_ENABLED, value: "true"}]. On Docker Compose set all three in the service's environment.
The gateway refuses to boot if MGMT_API_ENABLED=true arrives without AUTH_TOKEN or without GOVERNANCE_ISSUED_KEYS=true, and names the missing one. Under GATEWAY_POSTURE=shared the flag is refused outright: MGMT_API_ENABLED must not be true: the Shared Gateway does not serve the management API yet (#210); teams manage keys in the web UI.
The surface is mounted at /api/v1/ on the main listener (port 8080 in the chart). Every call authenticates with a management key as a bearer token, and every non-2xx response has one shape:
The code values are unauthorized, forbidden, invalid_request, not_found, conflict, timeout and internal.
Step 3: List and create runtime keys
Export the ops-automation plaintext as $NAUTILI_MGMT_KEY and list the team's runtime keys.
The response lists runtime keys only, trimmed here to the fields that matter. Management keys are never enumerable here, and revoked keys are absent.
limit defaults to 50 and tops out at 200. next_offset is null on the last page.
Now create a key. The body accepts name, expires_at and policy_id only. Kind, scopes, owner and custody are rejected as unknown fields, so this route mints plain service runtime keys with Auto custody (shown as Legacy in the dashboard's Custody column). Anything else is issued in the dashboard.
A 201 carries the plaintext in key. No later route returns it.
If you pass a policy_id and the binding fails, the gateway revokes the key it minted and returns the binding error, so you never hold a plaintext for a half-created key.
Step 4: Rotate a key with a grace window
Rotation swaps the secret in place. The id, the guardrail binding, the custody and the expiry all stay. The old plaintext keeps authorizing for grace_seconds, then stops on its own. There is nothing to revoke afterwards.
The response is the same shape as create: the key resource plus a fresh key. Omitting the body or sending 0 uses the control plane default of 24 hours. The ceiling is 7 days; above that you get 400 invalid_request with grace_seconds must not exceed 604800.
The sequence from CI:
- Call rotate and capture
key. - Write the new value into your secret store and roll your deployments.
- Do nothing else. When the grace ends the old value stops working and anything still carrying it fails with the dead-key
401.
The dashboard has the same operation: Rotate on a key row, with the 24-hour grace fixed.
Step 5: Disable, re-enable and revoke
Disabling is reversible. Revoking is not. PATCH carries the first, DELETE carries the second.
The PATCH returns the key resource with "disabled": true; send {"disabled": false} to re-enable. The DELETE returns 204 with no body and the key leaves GET /api/v1/keys for good. Its guardrail binding stays so trailing usage is attributed, and GET /api/v1/keys/{id}/usage still answers for it.
PATCH also takes name and expires_at, and separately policy_id to bind or unbind a guardrail (null unbinds). Metadata fields and policy_id cannot share one request. Binding a guardrail to an owned key returns 409 conflict, because an owned key follows its owner.
In the dashboard, Revoke on a key row confirms with Revoke permanently. To pause a key instead, use the PATCH above or Disable on the key's row on the Governance page.
Step 6: Decide who pays with custody
Custody is the second question. Each runtime key resolves to one of three arms:
| Custody | Forwards with | If that credential cannot be resolved |
|---|---|---|
Custodymanaged | Forwards withThe DevZero-provisioned credential for your team on the decided upstream. | If that credential cannot be resolvedDenied. Never falls back to your key. |
Custodybyok | Forwards withYour own provider credential from the Provider keys screen. | If that credential cannot be resolvedDenied. Never falls back to DevZero's key. |
| Custodyauto (unset) | Forwards withYour own credential when the team holds one for the decided upstream, otherwise the DevZero-provisioned one. | If that credential cannot be resolvedFalls back down that ladder. |
An explicit binding fails closed. An unbound key falls back. That is the whole trade, and why the dashboard prints the consequence under the Custody column, not only the label.
Here is the setup where one team pays through its own OpenAI account and another uses DevZero-managed keys.
On the paying team, open Provider keys. Under Forwarding credentials find the card for your upstream, for example Your OpenAI key (on an OpenRouter-only deployment it is Your OpenRouter key), and click Connect. The Connect OpenAI dialog asks for a Name (for example prod) and the API key, and makes one test call to the provider before saving. The saved card shows the last four characters with a Connected chip, or Not verified if that call failed. A team may hold several named credentials per provider, with exactly one default.

Then issue that team's runtime key with Custody set to BYOK. The form refuses to mint a BYOK key while the team holds no credential (Paste your provider key first). Optionally pick a Forward credential to pin the key to one named credential instead of the provider default.
On the other team, leave the card disconnected and issue keys with Custody set to Managed. If the team is not enrolled in DevZero-managed billing yet, the button reads Enrol & issue and enrolment happens first; on an upstream without a key-provisioning API the Managed option is disabled with the reason. Those keys forward with the credential DevZero provisioned for that team, and the spend lands on DevZero's invoice to you.
Requests on either key are otherwise identical. The difference shows in the X-Dz-Serving-Path response header in router mode, which ends in @byok or @managed, and in the custody arm Spend groups into Your own provider keys versus Managed by DevZero.
Step 7: Read what a key has spent
Two routes, both needing usage:read. The first takes a key id in the path. The second takes any principal.
Both return the same shape. Trimmed to the fields you will act on:
Amounts are micro-USD integers, so 50000000 is $50. Three rules for reading it:
- Spend is reported against the governing guardrail, not the key alone.
alice-laptopshares Alice's bucket, sobucket_spent_micro_usdcan move because of traffic the key never carried.principal_spent_micro_usdis the key's own contribution. - A value that does not apply or is not yet known is a literal
null, never0. Checkprincipal_spent_completebefore treating the figure as a total. principal_kind=identitywith a DevZero user id asprincipal_refreads a person's spend; an emptyprincipal_refreads the unattributed bucket.principal_kindis required and no other query parameters are accepted.
Verify
- API keys shows the three rows from Step 1 with
alice-laptopunder Alice's name in the Guardrail column andci-deployon the team default. - After Step 4, the rotated key's row keeps its id and Custody value and the old plaintext returns
401once the grace window passes. Test with any inference request:
- After Step 6, a request on the BYOK key returns
X-Dz-Serving-Pathending in@byokand appears under Your own provider keys on Spend. The managed team's requests land under Managed by DevZero.
Options
custody
Set at issue time in the Custody field. The management API create route does not accept it, so a key created there is Auto. A BYOK key whose team credential is deleted later is denied, not moved:
Reconnect the credential on Provider keys. An Auto key in the same situation falls through to the DevZero-provisioned credential and keeps working.
grace_seconds
Body of POST /api/v1/keys/{id}/rotate. 0 or omitted means 24 hours. Maximum 604800 (7 days). Negative or larger values return 400 invalid_request. Pick the shortest window your deploy pipeline reliably completes in.
expires_at
RFC 3339 timestamp on create and on PATCH; null on PATCH clears it. An expired key gets the same dead-key 401 as a revoked one.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Symptom401 {"error":{"code":"unauthorized","message":"invalid or missing management key"}} | CauseMissing bearer, a non-sk-dz- token, or a management key that is unknown, expired, disabled or revoked. The message is identical for all of these on purpose. | FixIssue a new management key in the dashboard. |
Symptom403 runtime keys cannot access the management API; use a management key | CauseYou sent a live runtime key to /api/v1/. | FixUse the management key. Kind cannot be changed after issue. |
Symptom403 management key lacks the "keys:write" scope | CauseThe key was issued with a scope list that excludes this route's scope. | FixIssue a new management key with the scope, or with no scopes to grant all four. |
Symptom404 key not found on a PATCH, DELETE or rotate | CauseUnknown id, another team's id, or a management key id. Indistinguishable by design. | FixCheck the id against GET /api/v1/keys. Management keys live in the dashboard only. |
Symptom409 {"error":{"code":"conflict", ...}} on PATCH with policy_id | CauseThe target is an owned key, which follows its owner's guardrail. | FixBind the guardrail to the owner on Guardrails, or issue a service key. |
Symptom409 conflict on GET /api/v1/usage?principal_kind=identity | CauseIdentity usage needs the fleet-wide coverage marker, which DevZero has not yet set on the control plane. Key-subject usage works regardless. | FixRead by principal_kind=key until the rollout completes. |
SymptomInference 403 with code credential_unavailable | CauseExplicit BYOK or Managed custody, and that credential cannot be resolved. | FixReconnect the credential on Provider keys, or re-bind the key. |
SymptomInference 403 with code custody_unsupported_upstream | CauseA Managed key routed to an upstream DevZero cannot provision a key on. | FixRegister your own credential for that upstream or route elsewhere. |
SymptomInference 403 with code key_policy_not_metered | CauseThe key resolves to a guardrail that is not BYOK or Managed, so there is no team-funded credential to forward on. | FixBind a BYOK or Managed guardrail to the key's owner or to the team default. |
SymptomInference 403 with code management_key | CauseA management key on an inference route. | FixUse a runtime key. |
SymptomGateway exits at boot naming MGMT_API_ENABLED | CauseAUTH_TOKEN empty, GOVERNANCE_ISSUED_KEYS not true, or GATEWAY_POSTURE=shared. | FixSet the missing variable, or manage keys in the dashboard on the Shared Gateway. |
Next steps
- Guardrails overview: bind budgets, rate ceilings and model access to the keys you issued, because a key only identifies the caller.
- Spend: see the Managed by DevZero and Your own provider keys arms you set up in Step 6 as dollars.
- Management API: the contract-versioning rules and the null-not-zero convention this guide relies on.
- Management reference: every route, parameter and schema, generated from the contract.
- Keys and credentials: the full custody ladder including the installation credential and the two BYOK tiers.
- Govern LLM traffic with guardrails: put budgets and model allowlists on the keys from Step 1.
- Reading the Spend screen: walk the custody arms and per-key spend you set up in Step 6.