Skip to Content
Getting startedAuthentication

Authentication

The Whatsaper API authenticates with tenant API credentials scoped to your account. There is no OAuth flow — you create a key in the app and send it with every request.

Create a key

In the Whatsaper app, open Settings → API Credentials, choose the scopes and workspaces the key may use, then create it. The raw key is returned once; store it in a secret manager.

Creating API credentials requires a plan that includes REST API access.

Send the key

Either header works:

# Preferred curl https://api.whatsaper.com/api/contacts \ -H "X-API-Key: YOUR_API_KEY" # Also accepted curl https://api.whatsaper.com/api/contacts \ -H "Authorization: ApiKey YOUR_API_KEY"

Keys are hashed at rest; only a short prefix is shown after creation, which you can use to identify a key in the dashboard.

Scopes

Each key carries a list of permission scopes. Scopes use the form <action>.<resource> (for example view.contacts, create.campaigns), and * grants everything the account can do. A request that needs a scope the key doesn’t hold returns 403.

Workspace binding

A key may be restricted to specific workspaces. When it is:

  • Send X-Workspace-ID or an accepted workspace_id field. A request without Workspace context returns 403.
  • Conflicting Workspace inputs return 400. An inaccessible Workspace may return 403 or 404.

Expiry, rotation, and revocation

  • Keys can have an expiry date; expired keys are rejected with 401.
  • Rotate a key to issue a replacement and revoke the old one in a single step.
  • Revoking a key is immediate.

Tenancy

Every key acts as the account that created it. You can only read and write your own account’s data — requests can never reach another tenant.

Last updated on