# Xác thực

Khóa API cho server, token ngắn hạn cho trình duyệt.

## Khóa API

Request tới `/v1` gửi khóa bí mật trong header `Authorization` (`GET /v1/models` là ngoại lệ, không cần khóa):

```bash
curl https://api.example.com/v1/credits \
  -H "Authorization: Bearer $SOTA_API_KEY"
```

- Khóa có dạng `sk_live_...`, tạo và thu hồi trong dashboard (**Khóa API**).
- Khóa đầy đủ chỉ hiện **một lần** khi tạo; sau đó chỉ còn prefix. Mất khóa thì tạo khóa mới và thu hồi khóa cũ.
- Thiếu, sai hoặc đã thu hồi khóa: `401 unauthorized`. Tài khoản bị tạm khóa: `403 account_suspended`.
- Giới hạn tốc độ tính **theo từng khóa**, xem [Giới hạn tốc độ](/docs-md/rate-limits.md).

> Khóa API là bí mật của server. Đừng nhúng vào ứng dụng web, app di động hay repo công khai.

## Token cho trình duyệt

Trình duyệt không đặt được header khi mở WebSocket và không được giữ khóa API. Thay vào đó:

1. Server của bạn gọi `POST /v1/tokens` bằng khóa API.
2. Server trả `token` (`tok_...`) cho trang web.
3. Trang mở WebSocket với `?token=tok_...`.

```bash
curl -X POST https://api.example.com/v1/tokens \
  -H "Authorization: Bearer $SOTA_API_KEY"
```

```json
{"object":"token","token":"tok_3q2r8mYwK1x0b7sN","expires_at":1763366700}
```

Quy tắc của token:

- Sống **5 phút** (300 giây) kể từ lúc tạo, xem `expires_at`. Hãy mở kết nối trước khi hết hạn; kết nối đã mở không bị cắt khi token hết hạn.
- Chỉ dùng được với `GET /v1/audio/speech/stream` (tham số `token`), không dùng cho route HTTP khác.
- Gắn với tài khoản của khóa đã tạo ra nó; credit trừ vào tài khoản đó.
- Origin của trang phải nằm trong danh sách cho phép của deployment.
- Tạo token theo yêu cầu (mỗi lần mở kết nối), đừng lưu lâu. Không ghi token vào log.
- Thu hồi khóa API **không** thu hồi các token đã cấp từ khóa đó: chúng vẫn hợp lệ đến hết TTL (300 giây).

Ví dụ endpoint trên server (Node.js, Express) cấp token cho trang đã đăng nhập:

```js
app.post('/sota-token', requireUser, async (_req, res) => {
  const r = await fetch('https://api.example.com/v1/tokens', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SOTA_API_KEY}` },
  });
  if (!r.ok) return res.status(502).end();
  const { token, expires_at } = await r.json();
  res.set('Cache-Control', 'no-store').json({ token, expires_at });
});
```

Phía trình duyệt xem [Voice agent qua WebSocket](/docs-md/realtime-websocket.md#browser).

