Skip to main content
The Reply API uses Bearer token authentication. Every request must include your API key in the Authorization header.

​
Get your API key

1

Sign in

Sign in to your Reply.io dashboard.
2

Open API key settings

Go to Settings → API Key.
3

Create or copy a key

Create a new API key or copy an existing one. Treat your API key like a password.

​
Authenticate a request

Include your API key as a Bearer token: 
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_API_KEY

​
curl example

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: 
{ "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: 
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 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
You only need one header.

​
Behavior and permission model

Master API keys use the same permission model as user API keys.
RequestBehavior
Master key onlyActs as the workspace owner
Master key + X-User-IdActs as the specified user (by ID)
Master key + X-User-EmailActs 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: 
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_ORG_API_KEY
X-USER-ID: 12345

​
Behavior and permission model

RequestBehavior
Organization key + X-USER-IDActs as the user with that ID
Organization key + X-User-Email + X-TEAM-IDActs as the user with that email in the given workspace
Organization key without impersonationRequest is rejected
User belongs to a different organizationRequest 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.