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

Send an empty JSON object, `{}`, with `Content-Type: application/json`.

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

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `refreshToken` | string |

<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 '{
  "refreshToken": "refreshToken"
}'
```

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