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

# Аутентификация в API CSBoard с помощью Bearer-токенов

> Сгенерируйте API-ключ csb_pub_ на странице профиля, передавайте его как Bearer-токен или параметр запроса и разберитесь в различиях между ключами для чтения и торговли.

Каждый запрос к API CSBoard (кроме `GET /v1/health`) должен содержать действительный API-ключ. Ключи относятся к пространству имён `csb_pub_`, имеют либо доступ только на чтение, либо торговый доступ и привязаны к вашему аккаунту CSBoard. Сервер хранит только SHA-256-хеш каждого ключа — сам секрет показывается один раз при создании и больше никогда, поэтому сохраните его в надёжном месте.

## Получение API-ключа

<Steps>
  <Step title="Откройте вкладку API в профиле">
    Перейдите на [csboard.com/profile?tab=api](https://csboard.com/profile?tab=api) и при необходимости войдите в аккаунт.
  </Step>

  <Step title="Сгенерируйте новый ключ">
    Нажмите **Generate key**. Выберите метку, отражающую назначение ключа (например, `price-tracker-prod`).
  </Step>

  <Step title="Скопируйте ключ немедленно">
    Ваш новый ключ `csb_pub_…` отображается только один раз. Скопируйте его в менеджер секретов или переменные окружения, прежде чем закрыть окно.
  </Step>

  <Step title="Включите торговлю (опционально)">
    Если вам нужно размещать ордера, найдите ключ в списке и переключите **Trading enabled**. Перед этим ознакомьтесь с предупреждением ниже.
  </Step>
</Steps>

<Warning>
  Возможность торговли отделена от доступа на чтение и должна быть явно включена для каждого ключа на странице профиля. Ключ без включённой торговли вернёт `403 trading_not_enabled` при попытке вызвать `POST /v1/orders`. Никогда не включайте торговлю на ключе, которым вы делитесь с третьими лицами или встраиваете в клиентский код.
</Warning>

## Передача ключа в запросах

Отправляйте ключ как Bearer-токен в заголовке `Authorization` в каждом запросе:

```bash theme={null}
curl https://csboard.com/v1/listings \
  -H "Authorization: Bearer csb_pub_..."
```

Для удобства вы также можете передать ключ как параметр запроса `api_key` — это полезно для быстрых тестов в браузере или инструментах, не поддерживающих пользовательские заголовки:

```bash theme={null}
curl "https://csboard.com/v1/listings?api_key=csb_pub_..."
```

В продакшене предпочитайте заголовок `Authorization`; параметры запроса с большей вероятностью попадают в логи сервера.

## Возможности ключей

| Возможность         | Ключ для чтения | Торговый ключ |
| ------------------- | --------------- | ------------- |
| Все эндпоинты `GET` | ✅               | ✅             |
| `POST /v1/orders`   | ❌               | ✅             |

<Tip>
  Создавайте отдельные ключи для разных задач (например, один ключ для чтения — для дашборда цен, другой — торговый — для бота-покупателя), чтобы их можно было отзывать независимо, не нарушая работу всего сразу.
</Tip>

## Безопасность и хранение

Мы храним только `SHA256(key)` — никогда сырой секрет. Это означает:

* Если вы потеряли ключ, придётся сгенерировать новый; опции «показать ключ» нет.
* Скомпрометированный ключ можно мгновенно отозвать из профиля без влияния на другие ключи.

## Ошибки аутентификации

Каждая ошибка API возвращает JSON-тело такого формата:

```json theme={null}
{ "code": "invalid_api_key", "detail": "Unknown or revoked API key." }
```

| HTTP-статус | `code`                 | Когда возникает                                                     |
| ----------- | ---------------------- | ------------------------------------------------------------------- |
| 401         | `missing_api_key`      | Ключ не передан или не начинается с `csb_pub_`                      |
| 401         | `invalid_api_key`      | Ключ не распознан или был отозван                                   |
| 401         | `too_many_failed_auth` | Слишком много неверных ключей с вашего IP — применён 5-минутный бан |
| 403         | `trading_not_enabled`  | Ключ действителен, но торговля для него не включена                 |
| 429         | `rate_limit_exceeded`  | Превышен лимит запросов для ключа                                   |

Подробнее об ошибке 429 и о том, как корректно делать back-off, см. [Лимиты запросов](/rate-limits).