Skip to content
SpeakDocs

Authenticate with the Speak AI API using access tokens

Exchange your Speak AI API key for an access token, send it in the x-access-token header, and refresh the pair before the 80 minute expiry ends.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

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

Token Expiry Action on Expiry
Access Token 80 minutes Call Refresh Token endpoint
Refresh Token 24 hours Re-authenticate via Get Access Token

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

POST/auth/accessToken

This endpoint allows you to obtain an access token by providing the necessary authentication credentials.

The request body for this endpoint should include the your authentication credentials. Upon successful authentication, the server will respond with a status of “success” and provide the your email, access token, and refresh token in the response data.

Request rules. The request body is entirely optional: you can post an empty JSON object. Authentication comes from your API key in the x-speakai-key request header, not from the body, and a missing or invalid key returns 401. A deactivated account returns 200 with a deactivated status rather than tokens. This endpoint is rate limited to 5 requests per minute per IP address.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
deviceType string Labels the kind of client requesting the token so the resulting session is identified correctly in your login history. Leave it out and the session is labeled as an API session. Send zapier when you want a plain token pair with no session recorded; in that case the refresh token you get back cannot be exchanged later, so request a new access token instead of refreshing. Any value outside the accepted list is rejected when the session is saved, and you still get a working access token but no session record and no usable refresh token. Optional string. Defaults to api when you omit it or send an empty value. Only web, android, ios, zapier and api are stored successfully. One of: web, android, ios, zapier, api.
Example request
curl -X POST 'https://api.speakai.co/v1/auth/accessToken' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data.email string
data.accessToken string
data.refreshToken string

Example response (Get Access Token), application/json.

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

404 Not Found

Response body, application/json.

Field Type
status string
requestId string
code integer
message string
hints string[]

Example response (Get Access Token - Failure (No value found for Speak AI Key)), application/json.

{
  "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."
  ]
}

Example response (Get Access Token - Failure - Invalid API Key), application/json.

{
  "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

POST/auth/refreshToken

This endpoint is used to refresh the access token by providing the refresh token in the request body.

The refreshToken expires in 24 hour.

Request Body

  • refreshToken (string, required): The refresh token used to obtain a new access token.

Response

  • status (string): Indicates the status of the request, where “success” means the request was successful.
  • data (object): Contains the new access token and refresh token.
  • accessToken (string): The new access token.
  • refreshToken (string): The new refresh token.

Request rules. You must send refreshToken in the body unless the request already carries Speak’s refresh token session cookie, which only browser clients signed in through Speak’s own web apps have. The server reads the body value first and falls back to that cookie, so an API integration that omits the field always gets a 404. This endpoint is rate limited to 5 requests per minute per IP address.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
refreshToken string The refresh token you received the last time you signed in or requested a token. Send it here to get back a new access token and a new refresh token. Refresh tokens are single use: once you exchange one, the old value stops working, so store the new one from the response and use that next time. Replaying an already used refresh token ends the whole session and forces a fresh sign in. A missing token, or one that does not match an active session, returns 404. A token that is expired, tampered with, or otherwise not valid returns 401. Must be a string. An empty value or a value that is not a string is treated as missing and returns 404. Sending a non-string value also cancels the cookie fallback, so send either a real token string or no field at all. Required for API callers, since the only alternative the server accepts is a browser session cookie.
Example request
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 '{}'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data.accessToken string
data.refreshToken string

Example response (Refresh Token), application/json.

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

404 Not Found

Response body, application/json.

Field Type
status string
requestId string
code integer
message string

Example response (Refresh Token - Failure - Invalid / Expired Token), application/json.

{
  "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."
}

Get an API key on the Speak AI developer page.

Navigation
All sections

Type to search…

↑↓ navigate↵ selectEsc close