---
title: "Authenticate with the Speak AI API using access tokens"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the Speak AI API using access tokens


import EndpointIndex from "@/components/api/EndpointIndex.astro";

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](/api/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**

```json
{
  "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.

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | [`/auth/accessToken`](#post-auth-access-token) | Get Access Token |
| `POST` | [`/auth/refreshToken`](#post-auth-refresh-token) | Refresh Token |

<h2 id="post-auth-access-token">Get Access Token</h2>

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`. |

<div slot="code">

<CodePanel label="Example request">

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

</CodePanel>

<ResponsePanel id="post-auth-access-token" statuses={[{"code":"200","description":"OK"},{"code":"404","description":"Not Found"}]}>

<div slot="status-200">

**`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`.

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

</div>

<div slot="status-404">

**`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`.

```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`.

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

</div>

</ResponsePanel>

</div>

<h2 id="post-auth-refresh-token">Refresh Token</h2>

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. |

<div slot="code">

<CodePanel label="Example request">

```bash
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 '{}'
```

</CodePanel>

<ResponsePanel id="post-auth-refresh-token" statuses={[{"code":"200","description":"OK"},{"code":"404","description":"Not Found"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.accessToken` | string |
| `data.refreshToken` | string |

Example response (Refresh Token), `application/json`.

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

</div>

<div slot="status-404">

**`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`.

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

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)
- [Export Speak AI transcripts and insights to a file](/api/exports/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-authentication).

Source: https://docs.speakai.co/api/authentication/index.mdx