Authentication Guide

Secure API access with multiple authentication methods

API Keys

OAuth 2.0

JWT

Scope-based

Authentication Methods

API Keys

Security:

High

Complexity:

Simple

Best for:

Server-to-server communication

Long-lived credentials for backend services and automation

Pros:

Simple to implement
No user interaction
Long-lived (90 days)
Revocable

Cons:

Must be stored securely
Shared secret
No user context

OAuth 2.0

Security:

Very High

Complexity:

Moderate

Best for:

User-facing applications

Delegated authorization for third-party applications

Pros:

User authorization
Granular scopes
Refresh tokens
Industry standard

Cons:

More complex
Requires redirect flow
Short-lived tokens

JWT Tokens

Security:

High

Complexity:

Moderate

Best for:

Session-based authentication

Stateless authentication with embedded claims

Pros:

Stateless
Self-contained
Cross-domain
Verifiable

Cons:

Cannot be revoked easily
Token size
Clock skew issues

API Keys

Generate and manage API keys for server-to-server authentication

Critical Security Warning

API keys grant full access to your account. Never commit them to version control or share them publicly. Store them in environment variables and rotate them regularly (every 90 days recommended).

Generate New API Key

curl -X POST https://api.wave.inc/v1/auth/keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["streams:read", "streams:write", "analytics:read"],
    "expires_in_days": 90
  }'

# Response: 201 Created
{
  "id": "key_abc123xyz",
  "key": "wave_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Production API Key",
  "scopes": ["streams:read", "streams:write", "analytics:read"],
  "expires_at": "2026-02-14T00:00:00Z",
  "created_at": "2025-11-14T00:00:00Z"
}

# ⚠️ CRITICAL: Save the "key" value immediately!
# It's shown only once and cannot be retrieved later.

Permission Scopes

Granular access control with scope-based permissions

*

Full access to all resources (admin only)

admin

streams:read

List and view stream details

read

streams:write

Create, update, and delete streams

write

analytics:read

Access analytics and viewer data

read

recordings:read

List and download recordings

read

recordings:write

Delete recordings

write

webhooks:read

List webhook configurations

read

webhooks:write

Create and manage webhooks

write

users:read

List team members

read

users:write

Invite and manage team members

write

billing:read

View billing and usage data

read

billing:write

Update subscription and payment methods

write

Principle of Least Privilege: Always grant the minimum scopes necessary. For example, if you only need to read analytics, use analytics:read instead of *.

OAuth 2.0 Flow

Authorization for user-facing applications

Authorization Code Flow

Step 1: Redirect to Authorization

https://auth.wave.inc/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=streams:read streams:write analytics:read&
  state=random_state_string

Step 2: Exchange Code for Token

curl -X POST https://auth.wave.inc/oauth/token \
  -d 'grant_type=authorization_code' \
  -d 'code=auth_code_from_callback' \
  -d 'client_id=your_client_id' \
  -d 'client_secret=your_client_secret' \
  -d 'redirect_uri=https://yourapp.com/callback'

# Response
{
  "access_token": "wave_oauth_access_xxxxx",
  "refresh_token": "wave_oauth_refresh_xxxxx",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "streams:read streams:write analytics:read"
}

Step 3: Refresh Access Token

curl -X POST https://auth.wave.inc/oauth/token \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=wave_oauth_refresh_xxxxx' \
  -d 'client_id=your_client_id' \
  -d 'client_secret=your_client_secret'

Security Best Practices

✓ Do

Store keys in environment variables
Use HTTPS for all API requests
Rotate keys every 90 days
Use minimal required scopes
Implement rate limiting on your end

✗ Don't

Commit keys to version control
Share keys in client-side code
Use same key for dev/staging/prod
Grant admin scopes unnecessarily
Ignore key expiration warnings