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

Journey — the first API call

Signup to a 200 response, and the one moment in it that cannot be recovered in the same session.

Editable source SVG draw.io All views
Integrating developer evaluating the platform Goal — Make one real API call today and decide whether to keep going Trigger — A tutorial, a colleague's recommendation, or a spike due Friday Done when — A 200 response in their own terminal, from their own key 1 · Sign up no key yet 2 · Create a key ◆ moment of truth 3 · Copy it ◆ moment of truth 4 · First call 5 · Go to production ◆ moment of truth What they do Creates an account Picks scopes Names the key Copies the secret Pastes into curl Moves key to CI Adds a live key What the platform does Issues a test key Scope picker defaults narrow Shows secret once Verifies locally Warns on scope width How it feels Delighted Fine Frustrated Where it hurts Which scopes do I need? Lost the secret, must re-create Test key silently fails on live What we do about it Scope presets per use case Rotate-in-place, not delete Environment in the prefix Journey — integrating developer, signup to first call The trough is the one-time secret display. It is deliberate, and rotation is what makes it survivable. v 1.0 · owner Security Platform Architecture · date 2026-09

The trough, and why it stays

  • Copying the secret is the low point, and it is caused by a deliberate decision: the platform keeps no recoverable copy. The fix is not to soften that — it is rotation, which turns a lost secret into a 30-second recovery rather than a support ticket.

What the architecture owes this journey

  • Scope presets, so a developer who does not yet know the vocabulary does not reach for the widest option.
  • Environment in the prefix, so a test key failing against live is legible in the error rather than in a support conversation.
  • Time to first call ≤ 2 minutes at p50 — a stated assumption, and the only NFR on this page that a developer can feel.

Risks

  • Narrow scope defaults raise the rate of second key creation. Accepted: a second key is cheap, an over-scoped first key is permanent.
  • The scope picker is the main place a well-designed vocabulary can still be defeated by a bad default.
◀  Actors and their Journeys All views Journey — a live key in a public commit  ▶
Solution Architecture v1.0 · Google Cloud with open-source edge components · Security Platform Architecture · 2026-0904-journey-first-api-call