Identity

The answer depends on the credential, not only on the person

This is the single most useful thing the endpoint tells you. One person, one project, three credentials, three different answers — all read back from a live gateway:

Read the first two rows together. The user token is the only one of the three carrying catalog.read and catalog.write; the API key is the only one carrying skill.write and model.write. So a call that works from the dashboard can fail from a script, and the reverse, with the same person behind both. That is not a bug to work around — it is the answer to "why does this work there and not here", and whoami is where you see it.

The fourth row makes the other half of the point: role stayed OWNER on that narrow key while grants held one entry. The role is not the permission. A grant check reads the grant list, so an admin role on a key with one grant buys nothing.

Reading a refusal with it

A missing grant refuses at the scope-resolution stage and names the grant it wanted:

error (S2:resolve-scope): token missing required grant "fabric:ontology.write"

Compare that string against the grants array and the answer is immediate: either the credential was minted too narrow, or your client is not sending the credential you think it is. Nothing else needs debugging first.

When to prefer the documentation tool

whoami is deliberately minimal. For a fuller picture in one call, POST /v1/docs with {"topic":"governance"} returns the same grants plus your project's mode, your live quota headroom and the gateway's own operating rules:

{
  "grants": ["fabric:query.read", "…"],
  "mode": "auto",
  "quota": { "org_window_max": 600, "org_window_used": 1,
             "project_window_max": 120, "project_window_used": 1 },
  "scope": { "org_id": "org_abc", "dept_id": "dept_abc", "project_id": "proj_abc",
             "user_id": "u_abc", "role": "OWNER", "grants": ["…"],
             "auth_kind": "api_key", "api_key_id": "key_Qu8IVcZ6cScOU3psqTEFHxTt" }
}

The scope.auth_kind field is worth the call on its own: api_key, user_jwt or session tells you which credential your client actually picked up; whoami reports it too. Use whoami for a cheap scope check in a health endpoint or a startup assertion; use the documentation tool when you are debugging.

A startup assertion worth writing

An unattended job that asserts its own scope at startup fails on the deployment rather than halfway through a run, when half the work is already done:

import os, urllib.request, json

req = urllib.request.Request(
    f"{os.environ['WEXA_BASE']}/whoami",
    headers={"Authorization": f"Bearer {os.environ['WEXA_API_KEY']}"},
)
me = json.load(urllib.request.urlopen(req))

assert me["project_id"] == os.environ["EXPECTED_PROJECT"], f"wrong project: {me['project_id']}"
assert "fabric:ontology.write" in me["grants"], "key cannot write the ontology"

The second assertion is the one that earns its place. A key rotated with the role default instead of the grants the old one carried looks identical until the first write is refused — and by then the job has already read, computed and partly committed.

• Authentication: How each credential type resolves to the scope this endpoint echoes.
• API keys: Minting a key with exactly the grants the job needs.
• Discovery: The uncredentialed counterpart, for clients that hold nothing yet.
• Core ideas: What an organization, department and project pin actually mean.