control plane api

API keys

Programmatic key management — the same operations as the dashboard's API keys page. The plaintext value appears exactly once, in the create response, and is never retrievable again.

Endpoints

method & path	does
`GET /admin/v1/orgs/:org_id/api_keys`	List the org's keys (metadata only — id, name, obfuscated prefix, created, last used).
`POST /admin/v1/orgs/:org_id/api_keys`	Mint a key. Body: { "name"?: string }. Response carries the one-time plaintext value plus metadata.
`DELETE /admin/v1/orgs/:org_id/api_keys/:key_id`	Revoke by key id. Ownership is verified against the org before deletion.

Create

request

curl -X POST https://api.understudylabs.com/admin/v1/orgs/$ORG_ID/api_keys \
  -H "Authorization: Bearer $UNDERSTUDY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "staging"}'

response (shape)

{
  "value": "sk_live_...",        // shown exactly once — store it now
  "metadata": {
    "id": "api_key_...",         // the durable reference; safe to log
    "name": "staging",
    "obfuscated_value": "sk_live_••••abcd",
    "created_at": "2026-06-12T00:00:00Z",
    "last_used_at": null
  }
}

last_used_at updates when the gateway validates the key on live traffic — useful for spotting keys that are safe to revoke.