Authenticate with the Speak AI API using access tokens

The Speak AI API exposes 2 authentication endpoints under the base URL https://api.speakai.co/v1. Every request needs the x-speakai-key and x-access-token headers described in Authentication.

All Speak AI API operations require two headers:

x-speakai-key: your_speak_ai_api_key_here

x-access-token: generated_access_token

Authentication Flow

1. Get Access Token: Call POST /v1/auth/accessToken with your x-speakai-key and Content-Type: application/json headers. The request body should be {} (empty JSON) when using API key authentication. On success, the response returns your accessToken and refreshToken inside the data object.

2. Use Access Token: Include the access token in the x-access-token header for all subsequent API calls, alongside your x-speakai-key.

3. Refresh Token: When the access token expires, call POST /v1/auth/refreshToken with both x-speakai-key and x-access-token headers (include the expired access token), and pass {"refreshToken": "..."} in the request body. You will receive a new accessToken and refreshToken pair.

Example Response

{
  "data": {
    "email": "you@example.com",
    "accessToken": "eyJhbG...",
    "refreshToken": "eyJhbG..."
  }
}

Token Expiry

Rate Limits

Both /v1/auth/accessToken and /v1/auth/refreshToken are limited to 5 requests per 60 seconds. Exceeding this returns 429 Too Many Requests.

Error Handling

• Expired Access Token: Returns 401 Unauthorized. Use the Refresh Token endpoint to obtain a new token pair.
• Expired Refresh Token: Returns an error response. Re-authenticate from scratch via the Get Access Token endpoint.
• Rate Limited: Returns 429. Wait and retry, implement exponential backoff for automated clients.

What can you do with the authentication endpoints?

Speak AI groups these 2 endpoints under the authentication resource. Each entry below links to the full reference for that endpoint further down this page.

Get Access Token

curl -X POST 'https://api.speakai.co/v1/auth/accessToken' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "email": "your_email_id",
    "accessToken": "access_token",
    "refreshToken": "refresh_token"
  }
}

{
  "status": "failed",
  "requestId": "ca665625-645e-438a-867d-366a6e3f133a",
  "code": 401,
  "message": "The authorization api key provided for the request is invalid.",
  "hints": [
    "The authorization api key provided for the request is invalid."
  ]
}

{
  "status": "failed",
  "requestId": "358bc130-e798-41c2-9864-2cd2ce9b766d",
  "code": 401,
  "message": "The authorization api key provided for the request is invalid.",
  "hints": [
    "The authorization api key provided for the request is invalid."
  ]
}

Refresh Token

curl -X POST 'https://api.speakai.co/v1/auth/refreshToken' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "refreshToken": "refreshToken"
}'

{
  "status": "success",
  "data": {
    "accessToken": "new_access_token",
    "refreshToken": "new_refresh_token"
  }
}

{
  "status": "failed",
  "requestId": "3fcf7e0c-a977-4c37-bae5-a72485206cd0",
  "code": 404,
  "message": "We were unable to find a valid token. Your token may have expired or invalid. Please contact development team."
}

Related pages

• API reference for the base URL, authentication, and the error format.
• Upload audio and video to Speak AI and read insights
• Create and update live transcription sessions in Speak AI
• Analyze text notes with the Speak AI text endpoints
• Export Speak AI transcripts and insights to a file

Get an API key on the Speak AI developer page.