Skip to content

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.
  • curl and jq. The Python and TypeScript tabs use requests and the built-in fetch.

Two questions get conflated whenever keys come up:

  1. Who is calling? Answered by the inbound credential, an sk-dz- key.
  2. 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:

NameKindOwnerCustodyScopesWhat it can do
alice-laptopKindRuntimeOwnerAliceCustodyleave unset (Auto)Scopesn/aWhat it can doInference only. Governed by Alice's guardrail and shares her budget bucket. Disabled automatically if Alice is offboarded.
ci-deployKindRuntimeOwnernone (service key)Custodyleave unset (Auto)Scopesn/aWhat 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-automationKindManagementOwnernoneCustodyn/aScopeskeys:read, keys:write, usage:readWhat 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.

The API keys screen with the Key, Status, Custody, Guardrail, Credit limit and Spend columns and the Advanced and New Key buttons

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.

MGMT_API_ENABLED=true
AUTH_TOKEN=<your control-plane service token>
GOVERNANCE_ISSUED_KEYS=true

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:

{"error": {"code": "forbidden", "message": "management key lacks the \"keys:write\" scope"}}

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.

curl -s https://<your-gateway-host>/api/v1/keys?limit=50 \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" | jq .

The response lists runtime keys only, trimmed here to the fields that matter. Management keys are never enumerable here, and revoked keys are absent.

{
"data": [
{
"id": "3f6c...",
"name": "ci-deploy",
"kind": "runtime",
"disabled": false,
"expires_at": null,
"last_used_at": "2026-10-09T08:12:44Z",
"policy_id": null,
"key_hint": "sk-dz-Ab…xyz"
}
],
"next_offset": null
}

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.

curl -s -X POST https://<your-gateway-host>/api/v1/keys \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "ci-preview", "expires_at": "2026-12-31T00:00:00Z"}'

A 201 carries the plaintext in key. No later route returns it.

{
"id": "9a21...",
"name": "ci-preview",
"kind": "runtime",
"disabled": false,
"expires_at": "2026-12-31T00:00:00Z",
"policy_id": null,
"key_hint": "sk-dz-Qr…m8K",
"key": "sk-dz-<43 characters>"
}

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.

curl -s -X POST https://<your-gateway-host>/api/v1/keys/<KEY_ID>/rotate \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" \
-H "Content-Type: application/json" \
-d '{"grace_seconds": 3600}'

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:

  1. Call rotate and capture key.
  2. Write the new value into your secret store and roll your deployments.
  3. 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.

# Disable
curl -s -X PATCH https://<your-gateway-host>/api/v1/keys/<KEY_ID> \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" \
-H "Content-Type: application/json" \
-d '{"disabled": true}'
# Revoke, permanently
curl -s -X DELETE https://<your-gateway-host>/api/v1/keys/<KEY_ID> \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" -w '%{http_code}\n'

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:

CustodymanagedForwards withThe DevZero-provisioned credential for your team on the decided upstream.If that credential cannot be resolvedDenied. Never falls back to your key.
CustodybyokForwards 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.

The Provider keys screen with the Your OpenAI key card showing Connected under Forwarding credentials

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.

curl -s https://<your-gateway-host>/api/v1/keys/<KEY_ID>/usage \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" | jq .
curl -s "https://<your-gateway-host>/api/v1/usage?principal_kind=key&principal_ref=<KEY_ID>" \
-H "Authorization: Bearer $NAUTILI_MGMT_KEY" | jq .

Both return the same shape. Trimmed to the fields you will act on:

{
"policy_id": "7d0e...",
"source": "team_default",
"active": true,
"counter_scope": "principal",
"pooled": false,
"limit_micro_usd": 50000000,
"window_start": "2026-10-01T00:00:00Z",
"reset": "2026-11-01T00:00:00Z",
"bucket_spent_micro_usd": 12410000,
"principal_spent_micro_usd": 12410000,
"principal_spent_complete": true,
"remaining_micro_usd": 37590000
}

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-laptop shares Alice's bucket, so bucket_spent_micro_usd can move because of traffic the key never carried. principal_spent_micro_usd is the key's own contribution.
  • A value that does not apply or is not yet known is a literal null, never 0. Check principal_spent_complete before treating the figure as a total.
  • principal_kind=identity with a DevZero user id as principal_ref reads a person's spend; an empty principal_ref reads the unattributed bucket. principal_kind is required and no other query parameters are accepted.

Verify

  • API keys shows the three rows from Step 1 with alice-laptop under Alice's name in the Guardrail column and ci-deploy on the team default.
  • After Step 4, the rotated key's row keeps its id and Custody value and the old plaintext returns 401 once the grace window passes. Test with any inference request:
curl -s https://<your-gateway-host>/v1/chat/completions \
-H "Authorization: Bearer <OLD_PLAINTEXT>" \
-H "Content-Type: application/json" \
-d '{"model": "anthropic/claude-haiku-4.5", "messages": [{"role": "user", "content": "ping"}]}'
{"error": {"message": "invalid DevZero API key: the key is unknown, revoked, expired, or disabled — ask a team admin to issue a new key", "type": "invalid_request_error", "code": "invalid_api_key", "param": "model"}}
  • After Step 6, a request on the BYOK key returns X-Dz-Serving-Path ending in @byok and 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:

{"error": {"message": "request for model \"openai/gpt-5.6-luna\" requires your organization's stored provider credential, but none is configured or reachable (policy 7d0e...)", "type": "invalid_request_error", "code": "credential_unavailable", "param": "model"}}

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

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 keyCauseYou 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" scopeCauseThe 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 rotateCauseUnknown 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_idCauseThe 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=identityCauseIdentity 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_unavailableCauseExplicit 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_upstreamCauseA 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_meteredCauseThe 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_keyCauseA management key on an inference route.FixUse a runtime key.
SymptomGateway exits at boot naming MGMT_API_ENABLEDCauseAUTH_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.

Ready to keep going?

Explore the next guide or start routing through Nautili.