A management key (rd_mk_…) is the non-interactive counterpart to a signed-in owner session: it authenticates the control plane (/v1) so scripts and CI can manage your account — projects, keys, limits, usage, logs — without a browser. This tutorial creates one and writes a small script that reads your projects, sets a quota, and pulls a usage summary.
A management key is org-scoped (no {env} segment), carries a role capped at admin, and is verified only by the control-plane API — the gateway has no knowledge of rd_mk_, so a management key can never call the data plane (chat, embeddings, images). Use a secret key for model traffic and a management key for management.

Prerequisites

  • You must be an org owner to issue a management key (a management key can never mint another).
  • The org id you are automating ($ORG_ID).

1. Create the management key

Issuing a management key is owner-only, so create it from the dashboard (organization settings → management keys). Give it a descriptive name and, optionally, an expiry. The plaintext is shown exactly once — copy it immediately; only its hash is stored. Store it as a secret in your CI provider (never commit it):

2. Verify the key: list your projects

A quick read confirms the key works and is scoped to your org. Listing projects requires the projects.read capability, which an admin-capped key has:
Some routes require an interactive user session and reject a management key with 403 — for example GET /v1/whoami and GET /v1/orgs (listing all your orgs). A management key already belongs to one org, so you address it directly by $ORG_ID rather than discovering it.

3. A CI script: read, configure, report

Here is a self-contained Node script that discovers a project’s environment, tightens a per-plan quota, and prints the current spend — the shape of a nightly guardrail job. It uses only fetch, so it needs no dependencies.
scripts/roadie-guardrail.ts
Run it in CI with ROADIE_MK and ORG_ID set:
Every mutating call (like the quota upsert) writes an entry to your org’s audit log, so you have an immutable record of what automation changed and when.

4. What a management key can and cannot do

5. Rotate and revoke

List and revoke keys as part of hygiene. Revocation is immediate — the control plane reads Postgres live, so a revoked key stops working on the next request with no propagation window:
Set an expires_at when you create a key for a time-boxed job so it lapses on its own.

What you built

You created an admin-capped management key and a dependency-free CI script that reads your projects, sets a quota, and reports spend — with every change recorded in the audit log. The key manages your account but can never touch model traffic, mint another key, or perform owner-level actions, and you can revoke it instantly. That is the safe surface for automating Roadie from CI.

Next steps

Per-user limits

The full set of limits, quotas, and budgets you can script.

Observability

Pull usage and logs from the same control-plane API.

Control-plane API

The complete, generated operation list.

Authentication

How management keys fit among the six credential types.