Get Started

Authenticate your client apps

Secure client access to Cartesia APIs using Access Tokens

You may want to make Cartesia API requests directly from your client application. However, shipping your API key to the app is not secure, as a malicious user could extract your API key and issue API requests billed to your account.

Access Tokens provide a secure way to authenticate client-side requests to Cartesia’s APIs without exposing your API key.

Prerequisites

Before implementing Access Tokens:

  1. Configure your server with a Cartesia API key
  2. Implement user authentication in your application
  3. Establish secure client-server communication

Available Grants

Access Tokens support granular permissions through grants. Both TTS and STT grants are optional:

TTS Grant: With grants: { tts: true }, clients have access to:

  • /tts/bytes - Synchronous TTS generation streamed with chunked encoding
  • /tts/sse - Server-sent events for streaming
  • /tts/websocket - WebSocket-based streaming

STT Grant: With grants: { stt: true }, clients have access to:

  • /stt/websocket - WebSocket-based speech-to-text streaming
  • /stt - Batch speech-to-text processing
  • /audio/transcriptions - OpenAI-compatible transcription endpoint

You can request multiple grants in a single token: grants: { tts: true, stt: true }

Coming Soon: Additional grants for /voices, /voice-changer, and other services

Implementation Guide

1. Token Generation (Server-side)

Make a request to generate a new access token:

$# TTS and STT access
>curl --location 'https://api.cartesia.ai/access-token' \
>  -H 'Cartesia-Version: 2025-04-16' \
>  -H 'Content-Type: application/json' \
>  -H 'Authorization: Bearer sk_car_...' \
>  -d '{ "grants": {"tts": true, "stt": true}, "expires_in": 60}'
>
># TTS-only access
>curl --location 'https://api.cartesia.ai/access-token' \
>  -H 'Cartesia-Version: 2025-04-16' \
>  -H 'Content-Type: application/json' \
>  -H 'Authorization: Bearer sk_car_...' \
>  -d '{ "grants": {"tts": true}, "expires_in": 60}'

Example Implementation

1// TTS and STT access
2const response = await fetch("https://api.cartesia.ai/access-token", {
3  method: "POST",
4  headers: {
5    "Content-Type": "application/json",
6    "Cartesia-Version": "2025-04-16",
7    Authorization: "Bearer <your_api_key>",
8  },
9  body: JSON.stringify({
10    grants: { tts: true, stt: true },
11    expiresIn: 60, // 1 minute
12  }),
13});
14
15// TTS-only access
16const responseTTS = await fetch("https://api.cartesia.ai/access-token", {
17  method: "POST",
18  headers: {
19    "Content-Type": "application/json",
20    "Cartesia-Version": "2025-04-16",
21    Authorization: "Bearer <your_api_key>",
22  },
23  body: JSON.stringify({
24    grants: { tts: true },
25    expiresIn: 60, // 1 minute
26  }),
27});
28
29const { token } = await response.json();

For detailed API specifications, see the Token API Reference.

2. Token Storage (Client-side)

Store the token securely, such as setting HTTP-only cookie with matching token expiration. The cookie should be httpOnly, secure, and sameSite: "strict".

3. Making Authenticated Requests

1// Using TTS with access token
2const ttsResponse = await fetch("https://api.cartesia.ai/tts/bytes", {
3  headers: {
4    Authorization: `Bearer ${accessToken}`,
5    "Content-Type": "application/json",
6  },
7  // ... request configuration
8});
9
10// Using STT with access token
11const sttResponse = await fetch("https://api.cartesia.ai/stt", {
12  method: "POST",
13  headers: {
14    Authorization: `Bearer ${accessToken}`,
15  },
16  body: formData, // multipart/form-data with audio file
17});

4. Token Refresh Strategy

Proactively refresh the token in your app before they expire.

Security Best Practices

Essential Guidelines

  • ✅ Generate tokens server-side only
  • ✅ Use short token lifetimes (minutes)
  • ✅ Implement automatic token refresh
  • ✅ Store tokens in HTTP-only cookies
  • ✅ Enable secure and SameSite cookie flags

Security Don’ts

  • ❌ Never store tokens in localStorage/sessionStorage
  • ❌ Never log tokens or display them in the UI
  • ❌ Never transmit tokens over non-HTTPS connections

Token Lifecycle Management

  1. Generate new token upon user authentication
  2. Implement automatic refresh before expiration
  3. Handle token expiration gracefully

Additional Resources