# GET /v1/whoami (/docs/api/reference/organizations/whoami)



<Endpoint method="GET" path="/v1/whoami" auth="Bearer" phase="1" />

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.

<Parameters
  title="Headers"
  rows="[
  { name: 'Authorization', type: 'string', required: true, description: <>API integration key. Format <code>Bearer lp_&lt;env&gt;_&lt;key_id&gt;_&lt;secret&gt;</code>.</> },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api.layers.com/v1/whoami \
      -H "Authorization: Bearer $LAYERS_API_KEY"
    ```
  </Tab>

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

  <Tab value="Python">
    ```python
    import os, requests

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

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "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
  }
  ```
</Response>

### Field notes [#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](/docs/api/concepts/api-keys#child-keys-for-sub-organizations) 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`](/docs/api/reference/credits/get-credits). Poll `/credits` directly when you need the detailed breakdown (per-format estimates, billing period, ingest-cost flags).

## Response headers [#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](/docs/api/operational/rate-limits).

## Errors [#errors]

| Status | Code                | When                                                                                           |
| ------ | ------------------- | ---------------------------------------------------------------------------------------------- |
| 401    | `UNAUTHENTICATED`   | Missing, malformed, or unrecognized key.                                                       |
| 402    | `BILLING_EXHAUSTED` | Org's plan does not include API integration access. `details.minTier` names the required tier. |
| 503    | `KILL_SWITCH`       | Key or organization has been disabled. The error message names the reason.                     |

## See also [#see-also]

* [Authentication](/docs/api/getting-started/authentication) - key format, header precedence, rotation.
* [API keys](/docs/api/concepts/api-keys) - lifecycle, revocation, kill-switch.
* [Rate limits](/docs/api/operational/rate-limits) - tier quotas and 429 handling.