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

​
Get your API key

1

Sign in

Log in to your Reply.io dashboard.
2

Open API key settings

Navigate to Settings → API Key.
3

Create or copy a key

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

​
Authenticate a request

Pass the key as a Bearer token in the Authorization header: 
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_API_KEY

​
curl

curl https://api.reply.io/v3/whoami \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Verify your setup

Call /v3/whoami to confirm the credentials are valid. A successful response returns your user ID: 
{ "userId": 12345 }

​
Unauthorized response

If the Authorization header is missing, malformed, or contains a revoked or unknown token, the API returns 401 Unauthorized with an empty body. The response advertises the expected scheme in the WWW-Authenticate header: 
HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Bearer
There is no JSON payload — clients should rely on the status code and header rather than parsing a response body.

​
Special API keys

Beyond the per-user key, the Reply API supports two centralized credentials that can act on behalf of other users: the Master API key for a single workspace, and the Organization API key for every workspace inside an organization.

​
Master API key — team level

The Master API key provides centralized, team-level access to the Reply API. Unlike a per-user key (which authenticates as the single user it belongs to), a master key can act on behalf of any user inside the workspace it was issued for — useful for team-wide automation, cross-user reporting, and bulk operations.

​
Availability

  • Workspace-scoped only. A master key authenticates calls within the single workspace it was generated in. For a credential that spans every workspace in an organization, see Organization API key below.

​
Permissions and access control

  • The master key can be generated and viewed only by the workspace owner.
  • It must be generated manually the first time — there is no auto-issue on workspace creation.
  • The master key is unique per workspace.

​
Acting on behalf of a user

The master key supports impersonation via additional request headers. Supported headers:
  • X-User-Id
  • X-User-Email
Only one header is required — it is not necessary to include both.

​
Behavior and permission model

All actions performed with the master key follow the same permission logic as per-user API keys.
ScenarioBehavior
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 system permissions and access restrictions of the impersonated user are applied.

​
Important notes

  • If impersonation headers are provided, the request is executed strictly within the permission scope of the specified user.
  • If no impersonation headers are provided, the request is executed with the workspace owner’s permissions.
  • The master key does not grant additional permissions beyond those defined by the resolved user context.

​
Organization API key — organization level (beta)

The Organization API key is a single credential that acts on behalf of any user inside the issuing organization. Unlike a master key — which is scoped to a single workspace — an organization key spans every workspace owned by the organization, making it the natural choice for automation that operates across the organization’s full footprint.

​
Availability

  • Organization-scoped. One organization key authenticates calls for any user in any workspace owned by the issuing organization.
  • Multiple organization keys can be issued per organization; each one can be named, revoked, and rotated independently.

​
Permissions and access control

  • Org Owners can create, list, and revoke organization API keys by default.
  • Other organization roles can be granted the Manage organization API keys permission by an Org Owner via the role-permissions screen; once granted, they gain the same management access.
  • Keys are managed from Org Settings → Organization API keys.

​
Acting on behalf of a user

Organization API keys require an impersonation header on every request — unlike the master key, there is no default user. Provide one of:
  • X-USER-ID — identifies the target user by ID.
  • X-User-Email together with X-TEAM-ID — identifies the target user by email within a specific workspace.
If neither is supplied, or X-User-Email is supplied without X-TEAM-ID, the request is rejected. 
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_ORG_API_KEY
X-USER-ID: 12345

​
Behavior and permission model

ScenarioBehavior
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 with no impersonation headersRequest is rejected
Resolved user belongs to a different organizationRequest is rejected
In all accepted cases, the system permissions and access restrictions of the impersonated user are applied.

​
Important notes

  • Every request is executed strictly within the permission scope of the resolved user.
  • The resolved user must belong to the same organization that issued the key.
  • The organization API key does not grant additional permissions beyond those defined by the resolved user context.

​
Keeping your key safe

  • Never commit your API key to source control or paste it into public chats.
  • Rotate the key from Settings → API Key if you suspect it was exposed.