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

# アプリケーションを認証する

> ブラウザではアクセストークンを、サーバーではAPIキーを使用する

このページの実装ガイドでは、ブラウザで[アクセストークン](/api-reference/auth/access-token)を使用し、信頼されたサーバーで[APIキー](https://play.cartesia.ai/keys)を使用する方法を説明します。

| 環境                        | 推奨される認証  | 理由                         |
| ------------------------- | -------- | -------------------------- |
| ブラウザアプリ                   | アクセストークン | APIキーがクライアントコードに露出するのを防ぎます |
| 信頼されたサーバー、スクリプト、またはノートブック | APIキー    | シンプルで、トークン交換が不要です          |

## サーバーサイドアプリ: APIキーを使用する

バックエンドサービス、ジョブ、ローカルスクリプト、ノートブックなどの信頼された環境からは、APIキーを直接使用してください。

Cartesiaは、サーバーサイド認証で `X-Api-Key` および `Authorization` ヘッダーの両方を受け入れます。ヘッダー名は大文字小文字を区別しないため、`X-API-KEY` や `authorization` でも動作します。

```typescript theme={null}
const ws = new WebSocket("wss://api.cartesia.ai/tts/websocket", {
  headers: {
    // "X-Api-Key": CARTESIA_API_KEY,
    // OR
    // "Authorization": `Bearer ${CARTESIA_API_KEY}`,
  },
});
```

上記のヘッダーベースのWebSocketの例は、カスタムヘッダーをサポートするサーバーサイドクライアント向けです。ブラウザでは、代わりにアクセストークンとクエリパラメータを使用してください。

## ブラウザアプリ: アクセストークンを使用する

ブラウザのコードにCartesia APIキーを絶対に同梱しないでください。ユーザーがそれを抽出し、あなたのアカウントでリクエストを行う可能性があります。

代わりに、サーバーで短期間有効なアクセストークンを生成し、そのトークンをブラウザに返してください。

## 前提条件

アクセストークンを実装する前に:

1. Cartesia API キーでサーバーを設定する
2. アプリケーションでユーザー認証を実装する
3. 安全なクライアント-サーバー間通信を確立する

### 利用可能なグラント

アクセストークンは、グラントによる細かい権限管理をサポートします。TTS と STT のグラントはいずれも任意です:

**TTS グラント**: `grants: { tts: true }` を指定すると、クライアントは次のエンドポイントにアクセスできます:

* `/tts/bytes` - チャンクエンコーディングでストリーミングされる同期 TTS 生成
* `/tts/sse` - ストリーミング用の Server-Sent Events
* `/tts/websocket` - WebSocket ベースのストリーミング

**STT グラント**: `grants: { stt: true }` を指定すると、クライアントは次のエンドポイントにアクセスできます:

* `/stt/websocket` - WebSocket ベースの音声テキスト変換ストリーミング
* `/stt` - バッチ音声テキスト変換処理
* `/audio/transcriptions` - OpenAI 互換のトランスクリプション エンドポイント

**エージェントグラント**: `grants: { agent: true }` を指定すると、クライアントは以下にアクセスできます:

* Agents WebSocket呼び出しエンドポイント

1つのトークンで複数のグラントをリクエストできます:

```json theme={null}
grants: { tts: true, stt: true, agent: false }
```

## 実装ガイド

### 1. トークン生成 (サーバー側)

cURL または公式クライアントライブラリを使用して、新しいアクセストークンを生成するリクエストを送信します:

<CodeGroup>
  ```bash cURL lines theme={null}
  # TTS and STT access
  curl --location 'https://api.cartesia.ai/access-token' \
    -H 'Cartesia-Version: 2026-03-01' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk_car_...' \
    -d '{ "grants": {"tts": true, "stt": true}, "expires_in": 60}'
  ```

  ```javascript JavaScript lines theme={null}
  import { CartesiaClient } from "@cartesia/cartesia-js";

  const client = new CartesiaClient({ apiKey: "YOUR_API_KEY" });

  // TTS and STT access
  await client.auth.accessToken({
    grants: {
      tts: true,
      stt: true
    },
    expires_in: 60
  });
  ```

  ```python Python lines theme={null}
  from cartesia import Cartesia

  client = Cartesia(
    token="YOUR_API_KEY"
  )

  # TTS and STT access
  response = client.auth.access_token(
    grants={"tts": True, "stt": True}, # Grant both permissions
    expires_in=60 # Token expires in 60 seconds
  )

  # The response will contain the access token
  print(f"Access Token: {response.token}")
  ```

  ```typescript JavaScript (fetch) lines theme={null}
  // TTS and STT access
  const response = await fetch("https://api.cartesia.ai/access-token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Cartesia-Version": "2026-03-01",
      Authorization: "Bearer <your_api_key>",
    },
    body: JSON.stringify({
      grants: { tts: true, stt: true },
      expires_in: 60, // 1 minute
    }),
  });

  const { token } = await response.json();
  ```
</CodeGroup>

詳細なAPI仕様については、[トークンAPIリファレンス](/api-reference/auth/access-token) を参照してください。

### 2. トークン保存 (クライアント側)

トークンの有効期限に合わせた HTTP-only クッキーを設定するなど、トークンを安全に保存します。クッキーは `httpOnly`、`secure`、`sameSite: "strict"` を設定してください。

### 3. API を使った認証済みリクエストの送信

```typescript lines theme={null}
// Using TTS with access token
const ttsResponse = await fetch("https://api.cartesia.ai/tts/bytes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  // ... request configuration
});

// Using STT with access token
const sttResponse = await fetch("https://api.cartesia.ai/stt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
  body: formData, // multipart/form-data with audio file
});
```

```typescript lines theme={null}
// Browser WebSocket (access token in query param)
const url = new URL("wss://api.cartesia.ai/tts/websocket");
url.searchParams.set("cartesia_version", "2026-03-01");
url.searchParams.set("access_token", accessToken);

const ws = new WebSocket(url);
```

### 4. トークンリフレッシュ戦略

各 API 呼び出しの前に、現在のトークンがまだ有効かどうかを確認します。期限切れまたは期限切れ間近の場合は、処理を続行する前にサーバーから新しいトークンをリクエストします。

```typescript lines theme={null}
async function getValidToken(): Promise<string> {
  if (!token || tokenExpiresAt < Date.now() + 5000) {
    // Token missing or expiring within 5 s — refresh
    const res = await fetch("/api/token");
    const data = await res.json();
    token = data.token;
    tokenExpiresAt = Date.now() + data.expires_in * 1000;
  }
  return token;
}
```

## セキュリティのベストプラクティス

### サーバー側

* トークンは必ずサーバー側のみで生成する — ブラウザのコードでは絶対に生成しない
* トークンの有効期間は短く (分単位) する
* トークンは HTTPS のみで配信する

### クライアント側

* トークンは HTTP-only クッキー (ブラウザが自動的に送信するが JavaScript からは読み取れないクッキー) に保存する
* クッキーの `secure` および `sameSite: "strict"` フラグを有効にする
* トークンを `localStorage` や `sessionStorage` に絶対に保存しない
* トークンをログに出力したり UI に表示したりしない

## 追加リソース

* [APIリファレンス](/api-reference/auth/access-token) - アクセストークン生成エンドポイントのドキュメント