Skip to main content
The Wave API authenticates with API keys sent as a Bearer token:

​
Key types

Sandbox and production are properties of a project, not of your account or organization. Each project has sandbox keys and production keys. Every new project starts in sandbox. A project goes live through its own Go-Live flow in the dashboard: you apply, a Wave admin reviews, assigns the project its own phone number, and Wave creates a sk_live_ key for it. Other projects of your organization stay as they are. Sandbox keys stay active after Go-Live. Some features (recordings, virtual numbers, queues) require a production key.

​
Getting a key

API keys are created and managed in the Wave dashboard (not via the API):
  1. Log in at wave.sa.
  2. Open API Keys.
  3. Copy the key on creation — it is shown once.
To rotate, use Revoke & Regenerate in the dashboard. The old key stops working immediately and a new one is issued atomically.

​
Scopes

Each key carries scopes that gate what it can do. Set them when you create or edit a key in the dashboard. A request for something outside a key’s scopes returns 403 INSUFFICIENT_PERMISSIONS.

​
Audit logs

GET /v1/audit-logs lists the changes in your project, newest first: API keys made and changed, webhooks, numbers and Go-Live steps. It is read-only and needs the audit:read scope. An API key gets the entries of its own project only. Keys made on the Keys page by an owner, an admin or an auditor get audit:read by default. A developer cannot give a key audit:read. The keys that Wave makes for you (at sign-up, when you create a project, and at Go-Live) do not get audit:read. A key without it gets 403 INSUFFICIENT_PERMISSIONS. In the portal, you can reveal a key only when your role may grant every scope the key holds. For example, a developer cannot reveal a key with audit:read, and an auditor cannot reveal a key that can make changes. In the portal, a member whose organization role is owner, admin or auditor also sees the organization-level changes (members, billing, sign-ins).
  • Filters: from and to (ISO 8601, inclusive), action, resource and resource_id (exact match).
  • Pages: limit (1–100, default 20). Pass next_cursor back as cursor for the next page; it is null on the last page.
  • Who made the change: actor is user (a member; user_id is set), system (Wave) or wave_operator (a Wave operator). A wave_operator entry does not show the operator’s identity or IP address.
  • Environments: a sandbox key and a production key of the same project get the same entries.
See the API reference for the full response.

​
Sending the key

Every request must include the Authorization header. Requests without a valid key return 401 with the standard error envelope.
Keep keys on your server and out of source control. The one exception is Web Calling: the browser SDK uses a webrtc:write key that Wave origin-locks to your allowed origins — scope that key to webrtc:write only and add it just to the origins you control.