GET /v1/whoami

Resolves the API key to its organization and returns a small payload you can use to fail fast if the key is misconfigured. Treat this as a cheap liveness probe, a boot-time sanity check, and the canonical way to render "you are authenticated as" in your UI.

A key is bound to exactly one Layers organization. If the key or its organization has been suspended, every endpoint - including this one - returns 503 KILL_SWITCH with a request id; a successful 200 from /whoami is itself the "not suspended" signal. Quote the X-Request-Id of any 503 to your Layers contact.

Example request

curl https://api.layers.com/v1/whoami \
  -H "Authorization: Bearer $LAYERS_API_KEY"

const res = await fetch("https://api.layers.com/v1/whoami", {
  headers: { "Authorization": `Bearer ${process.env.LAYERS_API_KEY}` },
});
const me = await res.json();

import os, requests

res = requests.get(
    "https://api.layers.com/v1/whoami",
    headers={"Authorization": f"Bearer {os.environ[\'LAYERS_API_KEY\']}"},
)
me = res.json()

Response

{
  "organizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
  "workspaceId": "org_2481fa5c-a404-44ed-a561-565392499abc",
  "organizationName": "Acme Growth",
  "parentOrganizationId": null,
  "scopes": [],
  "rateLimitTier": "standard",
  "apiKeyId": "key_c2037bb9-354d-4662-96b7-97a28ad6b6e1",
  "creditBalance": 2540
}

Field notes

• organizationId and workspaceId are UUIDs. Today they resolve to the same value for partner keys; a future workspace split may diverge them.
• scopes is the key's granted scopes as a flat string array (e.g. ["org:admin"]); empty for a legacy / unscoped key. Use it to render or assert what the key can do. (Partner keys today carry org-level access, so it's often returned empty — don't key behavior off length until granular scopes are populated.)
• parentOrganizationId (org_…) names the parent organization this key's org reports to. It's null for a top-level / partner org with no parent, and set for a child key minted under a sub-organization. Use it to tell a parent control-plane key apart from a per-customer child key.
• rateLimitTier reflects the key's bucket. standard is the default for self-serve partner keys; higher tiers (pilot, partner) are provisioned by Layers for design-partner and enterprise accounts. The fourth value, internal, identifies Layers-owned keys (admin tooling, internal dashboards) - partners will never see this on a self-serve key but the field is typed against the full enum, so don't hard-error on unknown values.
• Access-suspension state is intentionally not exposed on the success body. If a key or org is suspended every endpoint - including /whoami - returns 503 KILL_SWITCH. A 200 here means access is live; treat any 503 as "stop the world" and quote the response's X-Request-Id to support.
• apiKeyId is safe to log - it's the public identifier of the key used for rate-limit attribution.
• creditBalance is the org's full wallet - includedRemaining + prepaidBalance at call time. Use this to gate a generate call without a second RTT to GET /v1/credits. Poll /credits directly when you need the detailed breakdown (per-format estimates, billing period, ingest-cost flags).

Response headers

Every response carries:

• X-Request-Id: req_<ulid> - echo in your logs when filing a support ticket.
• X-Layers-Api-Version: v1 - informational.
• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Endpoint-Class, X-RateLimit-Tier. See rate limits.

Errors

See also

• Authentication - key format, header precedence, rotation.
• API keys - lifecycle, revocation, kill-switch.
• Rate limits - tier quotas and 429 handling.