API Key and Token Service  ·  View 03 of 22  ·  Act 2 · People and journeys

Actors and their Journeys

Six actors, each with a goal in their own words, and the things they actually get to do.

Editable source SVG draw.io All views
Customer engineering Integrating developer 40,000 / month Goal — Get a working key, paste it into my app, and make a real call before my coffee goes cold. Core journeys First successful API call ≤ 2 min at p50 Add a key per environment Service owner on call one per integration Goal — Rotate a key without taking my own production down, and prove the old one is idle before I kill it. Core journeys Rotate with an overlap window Retire a key nobody uses Customer security and governance Customer security engineer 1 per 12 developers Goal — When a key is on the internet, kill it everywhere in seconds and tell me exactly what it did before I did. Core journeys Contain a leaked key ≤ 60 s to action Review keys with no owner Export the audit trail Platform side Platform service owner 180 services Goal — Verify every request without adding a network hop, and know how stale my answer is. Core journeys Embed the verification library Read the staleness signal Platform SRE follow-the-sun Goal — See revocation propagation as a live number, not as a promise in a design document. Core journeys Watch the revocation canary Run a regional failover Machines and outsiders Scanning partner 3 integrated hosts Goal — Tell me whether this string I found in a public commit is live, and nothing else about it. Core journeys Confirm a candidate string Customer CI system automated issuance Goal — Mint a scoped, short-lived credential per deploy and never store a long-lived one. Core journeys Mint a per-deploy token Who this is for, and what each of them gets to do Person or role Journey / task Application we own External / third party Security / platform Two journeys carry the value and get their own map: the first call, and the leaked key. v 1.0 · owner Security Platform Architecture · date 2026-09

Why these six

  • The integrating developer decides whether the platform gets adopted at all; the security engineer decides whether it keeps its customers after an incident.
  • The platform service owner is an actor, not an implementation detail: the verification library is a product with its own adoption problem.
  • The scanning partner is an actor the platform does not control and cannot authenticate, which is why its interface is one bit wide.

What the goals reveal

  • "Prove the old one is idle before I kill it" is why last_used_at exists, and why it may be lossy — it informs a human, it does not authorise anything.
  • "Know how stale my answer is" is a requirement on the response shape, not on the documentation.
  • "Tell me what it did before I did" is why audit retention outlives the credential by years.

Deliberately absent

  • No "administrator" actor. Every privileged action belongs to a named principal in a tenant, and platform support is modelled explicitly as someone who cannot read secrets.