Worked identity and org-context samples
Bootstrap the session, then decide: callGET /api/v1/me at startup before touching any resource operation, read data.user, data.tenant, and data.organizations out of the same envelope, and branch on the caller’s role before you call a write path.
Every signed-in client resolves identity through this probe — the dashboard’s org picker and the mobile client both bootstrap from it. Cache the response per session, keep meta.request_id for support correlation, and re-fetch only on org switch or role change.
Read the authenticated caller
GET /api/v1/medata keys always arrive together: user carries the identity fields above plus the caller’s per-user preferences (softphone layout, voicemail-to-email opt-in, inbox signature), tenant is the organization context every subsequent request runs in, and organizations lists every membership with the caller’s role in each.
Preflight: decide on the caller’s role
Branch on
data.user.role / membership role before calling a write pathdata.user), which organization the key is bound to (data.tenant.slug), and whether the caller’s role in that org justifies the call you are about to make (data.organizations[].role). A workspace-scoped key resolves to exactly one tenant; multi-org dashboard (Clerk-session) callers receive every membership in data.organizations. An admin-of-one-org membership appears alongside the rest — treat the per-org role as the decision input and the org-scoped endpoint’s own verdict as authoritative.
A
200 on /me tells you the credential is good — it never tells you a write will succeed. Read the role, decide, and treat the operation’s own 403 as the authoritative verdict when the table disagrees with your role map.
Errors worth branching on
This probe is where an invalid credential surfaces first — an integration that skips the bootstrap re-discovers the same401 on every later call. The mechanics of the envelope (error.code / message / status / details, the meta.docs_url trail) are owned by the error handling guide; only the /me-specific branch is hers.
401 — the credential itself fails
401 on this probe means the X-API-Key header value itself fails — it never means the identity payload moved. The failure precedes tenant resolution, so there is no data envelope to fall back to. Read meta.docs_url for the code’s remedy anchor; rotate the key or mint a new one, because retrying the same header re-fails identically.
Retry matrix
The platform-wide retry-vs-terminal decision table lives in the error handling guide.