API Keys

API keys authenticate your applications and scripts when making requests to the WAVE platform. This guide covers key types, creation, rotation, scope management, and security best practices.

Key types

WAVE provides two types of API keys, each designed for different use cases:

Publishable keys

Publishable keys are safe to include in client-side code (browser, mobile apps). They can only perform read operations and initiate viewer sessions. They begin with the prefix wave_pub_.

Use for:

• Embedding the WAVE player in your website
• Client-side viewer authentication
• Public analytics queries

Secret keys

Secret keys provide full access to the WAVE API and must never be exposed in client-side code. They begin with the prefix wave_sk_.

Use for:

• Server-side stream management (create, update, delete)
• Webhook signature verification
• Billing and account management API calls
• CI/CD integrations

{% callout type=“error” title=“Never expose secret keys” %} Secret keys must only be used in server-side code. Never include them in browser JavaScript, mobile app bundles, or public repositories. If a secret key is compromised, revoke it immediately and generate a new one. {% /callout %}

Create an API key

{% stepper %} {% step title=“Navigate to API Keys” %} Open the WAVE dashboard and go to Settings > API Keys. {% /step %}

{% step title=“Click Create Key” %} Click the Create API Key button. Choose the key type (publishable or secret). {% /step %}

{% step title=“Configure scopes” %} Select the permission scopes for the key. Available scopes include:

• streams:read — View stream details and status
• streams:write — Create, update, and delete streams
• analytics:read — Access viewer and stream analytics
• billing:read — View invoices and usage
• billing:write — Modify payment methods and plans
• team:read — View team members
• team:write — Invite and remove team members {% /step %}

{% step title=“Set an expiration (optional)” %} You can set an expiration date for the key. Expired keys stop working automatically. For keys used in production integrations, we recommend setting a 90-day expiration and rotating before it expires. {% /step %}

{% step title=“Copy the key” %} The full key is displayed only once. Copy it and store it securely (e.g. in your environment variables or a secrets manager like AWS Secrets Manager, Vault, or Doppler). {% /step %} {% /stepper %}

Rotate a key

Key rotation replaces an existing key with a new one. The old key continues to work for a configurable grace period (default: 24 hours), giving you time to update your applications.

{% stepper %} {% step title=“Select the key to rotate” %} In Settings > API Keys, find the key you want to rotate and click the Rotate button. {% /step %}

{% step title=“Set grace period” %} Choose how long the old key should remain valid (1 hour, 24 hours, 7 days, or immediate revocation). {% /step %}

{% step title=“Update your application” %} Copy the new key and update your environment variables or secrets manager. Deploy the change before the grace period expires. {% /step %} {% /stepper %}

{% callout type=“tip” title=“Automate rotation” %} Use the WAVE API to rotate keys programmatically. This lets you integrate key rotation into your CI/CD pipeline or secrets management workflow. See the API Reference for the POST /api/v1/keys/rotate endpoint. {% /callout %}

Rate limits

API rate limits depend on your plan and key type:

Plan	Publishable key	Secret key
Starter	100 req/min	60 req/min
Pro	500 req/min	300 req/min
Business	2,000 req/min	1,000 req/min
Enterprise	Custom	Custom

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Security best practices

1. Use the minimum required scopes. Do not create keys with *:write scopes unless the integration needs write access.
2. Rotate keys regularly. Set calendar reminders or automate rotation every 90 days.
3. Use environment variables. Store keys in WAVE_API_KEY environment variables, not in code.
4. Monitor key usage. Check the API Keys > Usage tab for unexpected patterns. Sudden spikes may indicate a compromised key.
5. Revoke unused keys. Delete keys for integrations that are no longer active.
6. Enable IP allowlisting. For secret keys, restrict usage to specific IP addresses or CIDR ranges in the key settings.

{% callout type=“warning” title=“Leaked key?” %} If you suspect a key has been leaked, revoke it immediately from Settings > API Keys by clicking the Revoke button. Generate a new key and update your applications. {% /callout %}

{% contact-support category=“account” /%}

{% related-articles /%}