> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paraform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller identity

<Info>
  **Required scopes:** `identity:read`<br />
  **Rate limit:** `default` tier, 120 requests per minute per key
</Info>

Returns who the presented key acts as. `principal` is `agency` for an agency integration key (it acts as the agency's API service principal) or `recruiter` for a recruiter's personal key (it acts as that recruiter). Read `principal` first: the remaining identity fields differ between the two.

`scopes` is the key's EFFECTIVE scope set: everything its `access` tier grants plus any scopes granted explicitly, so it is the list scope checks evaluate. An `ALL` key reports the full scope vocabulary, not an empty list. A recruiter's personal key only ever reports recruiter scopes: its `access` tier adds no agency scope. `environment` is the key's environment (`live` when none is recorded). `email` is null when the recruiter has no email on file.

## Response

The response takes one of 2 shapes.

<Expandable title="principal: 'agency'" defaultOpen>
  <ResponseField name="principal" type="string" required>
    Allowed values: `agency`.
  </ResponseField>

  <ResponseField name="clientId" type="string" required />

  <ResponseField name="agencyId" type="string" required />

  <ResponseField name="name" type="string" required />

  <ResponseField name="access" type="string" required>
    Allowed values: `ALL`, `READ_ALL`.
  </ResponseField>

  <ResponseField name="scopes" type="string[]" required />

  <ResponseField name="environment" type="string" required />
</Expandable>

<Expandable title="principal: 'recruiter'" defaultOpen>
  <ResponseField name="principal" type="string" required>
    Allowed values: `recruiter`.
  </ResponseField>

  <ResponseField name="referrerUserId" type="string" required />

  <ResponseField name="userId" type="string" required />

  <ResponseField name="email" type="string | null" required />

  <ResponseField name="name" type="string" required />

  <ResponseField name="access" type="string" required>
    Allowed values: `ALL`, `READ_ALL`.
  </ResponseField>

  <ResponseField name="scopes" type="string[]" required />

  <ResponseField name="environment" type="string" required />
</Expandable>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/identity" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "principal": "agency",
    "clientId": "string",
    "agencyId": "string",
    "name": "string",
    "access": "ALL",
    "scopes": [
      "string"
    ],
    "environment": "string"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.