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

# Authentication

> Learn how to authenticate requests and manage API keys.

The Reply API uses Bearer token authentication. Every request must include your API key in the `Authorization` header.

## Get your API key

<Steps>
  <Step title="Sign in">
    Sign in to your [Reply.io dashboard](https://run.reply.io).
  </Step>

  <Step title="Open API key settings">
    Go to **Settings → API Key**.
  </Step>

  <Step title="Create or copy a key">
    Create a new API key or copy an existing one. Treat your API key like a password.
  </Step>
</Steps>

## Authenticate a request

Include your API key as a Bearer token:

```http theme={null}
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_API_KEY
```

### curl example

```bash theme={null}
curl https://api.reply.io/v3/whoami \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Verify your setup

Call `/v3/whoami` to verify that your API key works. A successful response returns information about the authenticated user:

```json theme={null}
{ "userId": 12345 }
```

## Unauthorized response

If the `Authorization` header is missing, invalid, or contains a revoked API key, the API returns `401 Unauthorized` with an empty response body.

The response includes a `WWW-Authenticate` header:

```text theme={null}
HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Bearer
```

Do not expect a JSON error response. Use the status code and headers to handle authentication failures.

## Special API keys

In addition to user API keys, Reply supports two centralized authentication methods:

* **Master API keys** for a single workspace
* **Organization API keys** for all workspaces in an organization

### Master API key — team level

A Master API key provides workspace-wide access.

Unlike a user API key, which always acts as a single user, a Master API key can make requests as any user in the workspace.

Common use cases include:

* Team-wide automation
* Cross-user reporting
* Bulk operations

#### Availability

* Available only within the workspace where it was created
* One Master API key per workspace
* Generated manually by the workspace owner

For a credential that spans every workspace in an organization, see [Organization API key](#organization-api-key-—-organization-level) below.

#### Permissions and access control

* Only the workspace owner can generate and view the Master API key.
* The key must be created manually.
* A Master API key is unique to its workspace.

#### Acting on behalf of a user

Use one of the following headers:

* `X-User-Id`
* `X-User-Email`

<Note>
  You only need one header.
</Note>

#### Behavior and permission model

Master API keys use the same permission model as user API keys.

| Request                     | Behavior                              |
| --------------------------- | ------------------------------------- |
| Master key only             | Acts as the workspace owner           |
| Master key + `X-User-Id`    | Acts as the specified user (by ID)    |
| Master key + `X-User-Email` | Acts as the specified user (by email) |

In all cases, the permissions of the resolved user are applied.

#### Important notes

* If an impersonation header is provided, the request runs with that user's permissions.
* If no impersonation header is provided, the request runs with the workspace owner's permissions.
* A Master API key does not grant permissions beyond those of the resolved user.

### Organization API key — organization level (beta)

An **Organization API** key provides centralized access across every workspace in an organization.

Unlike a Master API key, which is limited to a single workspace, an Organization API key can act on behalf of users across all workspaces owned by the organization.

#### Availability

* Organization-scoped
* Works across all workspaces in the organization
* Multiple keys can be created
* Keys can be named, revoked, and rotated independently

#### Permissions and access control

By default, Organization Owners can create, view, and revoke organization API keys.

Other organization roles can be granted permission to manage organization API keys.

Keys are managed in: **Org Settings → Organization API Keys**

#### Acting on behalf of a user

Organization API keys always require impersonation.

Use one of the following:

* `X-USER-ID`
* `X-User-Email` together with `X-TEAM-ID`

If no impersonation header is provided, the request is rejected.

If `X-User-Email` is provided without `X-TEAM-ID`, the request is rejected.

Example:

```http theme={null}
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_ORG_API_KEY
X-USER-ID: 12345
```

#### Behavior and permission model

| Request                                         | Behavior                                                |
| ----------------------------------------------- | ------------------------------------------------------- |
| Organization key + `X-USER-ID`                  | Acts as the user with that ID                           |
| Organization key + `X-User-Email` + `X-TEAM-ID` | Acts as the user with that email in the given workspace |
| Organization key without impersonation          | Request is rejected                                     |
| User belongs to a different organization        | Request is rejected                                     |

In all accepted requests, the permissions of the resolved user are applied.

#### Important notes

* Every request runs with the permissions of the resolved user.
* The resolved user must belong to the same organization that issued the key.
* An Organization API key does not grant permissions beyond those of the resolved user.

## Keep your API key safe

* Never commit API keys to source control.
* Never share API keys in public chats or screenshots.
* Rotate your API key from **Settings → API Key** if you think it has been exposed.