Authentication

All API requests must be authenticated using a Bearer token in the Authorization header.

Creating a Token

1. Go to app.wave.co/settings/developer-api

2. Click "Create Token" and give it a descriptive name

3. Select the permissions (scopes) your application needs

4. Copy the token immediately - it will only be shown once

Using Your Token

Include your token in the Authorization header with every request:

curl -H "Authorization: Bearer wave_api_xxx..." \
  https://api.wave.co/v1/sessions

Scopes

Tokens are granted specific permissions (scopes) that control what data they can access:

Token Security

• Tokens are only shown once when created - store them securely
• Tokens expire after 1 year but can be revoked at any time
• Use environment variables to store tokens, never commit them to code
• Create separate tokens for different applications
• Revoke tokens immediately if they may have been compromised

Error Responses

Authentication errors return appropriate HTTP status codes:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Token is invalid, expired, or revoked"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'transcripts:read' scope"
  }
}