# Alfa API: Получить токен Alfa ID

Сценарий из mcp-everything. Актуально на 2026-10-13.

Нужен перед вызовом методов, которые принимают `Bearer {access_token}`. Сценарий заканчивается получением `access_token`, `refresh_token` и `id_token`.

1. Создай интеграцию на Портале разработчика, подключи нужные scopes и получи `client_id` и `client_secret`. Для песочницы установи выданный тестовый TLS-сертификат.
2. Перенаправь пользователя на GET /oidc/authorize с `response_type=code`, `client_id`, `redirect_uri`, `scope` и `state`.
3. Получи `code` в `redirect_uri` и в течение двух минут однократно обменяй его на токены: POST /oidc/token с `grant_type=authorization_code`.
4. Передавай полученный токен как `Authorization: Bearer {access_token}`. По истечении часа вызови POST /oidc/token с `grant_type=refresh_token` и сохрани новую пару токенов.

```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code={code}' \
  --data-urlencode 'client_id={client_id}' \
  --data-urlencode 'client_secret={client_secret}' \
  --data-urlencode 'redirect_uri={redirect_uri}' \
  --data-urlencode 'code_verifier={code_verifier}'
```

## Базовые URL

- Боевой хост: `https://baas.alfabank.ru`
- Тестовый хост: `https://sandbox.alfabank.ru`
- Авторизация пользователя в боевой среде: `https://id.alfabank.ru/oidc/authorize`
- Авторизация пользователя в песочнице: `https://id-sandbox.alfabank.ru/oidc/authorize`
- Продукты и сервисы: `https://baas.alfabank.ru/api`
- Продукты и сервисы в песочнице: `https://sandbox.alfabank.ru/api`
- Alfa ID: `https://baas.alfabank.ru/oidc`
- Alfa ID в песочнице: `https://sandbox.alfabank.ru/oidc`

## Авторизация

Тип: OAuth 2.0

Alfa ID использует OAuth 2.0/OIDC. Для Authorization Code Flow нужны `client_id`, `client_secret`, `redirect_uri` и scopes подключённых продуктов; токен передаётся в заголовке `Authorization: Bearer {access_token}`. Alfa ID подходит для всех типов интеграций и продуктов.

Для части B2B- и H2H-методов доступен API Key: передавай `Authorization: ApiKey {API Key}`. Внутренний ключ предназначен для операций по своей компании, внешний — по другой компании; API Key доступен не для всех продуктов, поэтому проверяй описание конкретного метода.

## Методы сценария

### GET /oidc/authorize — Получение кода авторизации

Перенаправляет пользователя в Alfa ID. При успехе возвращает HTTP `302 Found`, а `code` приходит в `Location` на зарегистрированный `redirect_uri`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-auth-code/v1/get-auth-code

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `response_type` | query | string | да | Значение code |
| `client_id` | query | string | да | Идентификатор сервиса |
| `redirect_uri` | query | string | да | Зарегистрированный URI перенаправления |
| `scope` | query | string | да | Области доступа; минимально необходим openid |
| `state` | query | string | да | Значение для защиты от межсайтовой подделки запросов |
| `nonce` | query | string | нет | Связывает клиентскую сессию с ID Token |
| `code_challenge` | query | string | нет | Код вызова PKCE |
| `code_challenge_method` | query | string | нет | Метод преобразования верификатора: plain или S256 |
| `prompt` | query | string | нет | Управляет повторным входом, согласием и выбором организации |
| `max_age` | query | string | нет | Максимальный возраст аутентификации |

### POST /oidc/token — Получение токена доступа

С `grant_type=authorization_code` обменивает код на `access_token`, `refresh_token` и `id_token`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-access-token/v1/get-access-token

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Content-Type` | header | string | да | application/x-www-form-urlencoded |
| `Accept` | header | string | да | application/json |
| `grant_type` | body | string | да | authorization_code |
| `code` | body | string | да | Код авторизации |
| `client_id` | body | string | да | Идентификатор сервиса |
| `client_secret` | body | string | да | Секретный ключ сервиса |
| `redirect_uri` | body | string | да | URI перенаправления |
| `code_verifier` | body | string | нет | Верификатор PKCE |

Пример ответа:

```json
{
  "access_token": "eyJraWQiOiJhbGZ...",
  "refresh_token": "13b8230b-b6bf-...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJraWQiOiJhbGZhLXR..."
}
```

### POST /oidc/token — Обновление токена доступа

С `grant_type=refresh_token` возвращает новую пару `access_token` и `refresh_token`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/token-update/v1/token-update

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Content-Type` | header | string | да | application/x-www-form-urlencoded |
| `Accept` | header | string | да | application/json |
| `grant_type` | body | string | да | refresh_token |
| `refresh_token` | body | string | да | Токен обновления |
| `client_id` | body | string | да | Идентификатор сервиса |
| `client_secret` | body | string | да | Секретный ключ сервиса |

## Нюансы

- В песочнице все вызовы Alfa API должны выполняться с mTLS. Тестовый сертификат и закрытый ключ выдаются после подключения; негативные сценарии песочницы могут отличаться от промышленной среды и спецификации метода.
- Код авторизации действует две минуты и используется один раз. `access_token` действует один час; `refresh_token` — 180 дней и может быть использован не более двух раз, после обновления сохраняй новую пару токенов.
- При `Content-Type: application/x-www-form-urlencoded` в cURL специальные символы `client_secret` нужно экранировать; `redirect_uri` экранировать не нужно. При отправке через Postman в режиме `x-www-form-urlencoded` специальное экранирование не требуется.
- API Key действует один год или бессрочно, но автоматически отзывается, если после последнего запроса прошло более 30 дней.
- `statementDate` допускает даты не ранее пяти лет от первого дня текущего года. Одна страница выписки содержит не больше 1000 операций.
- `externalId` платёжного поручения назначает партнёр. Документация требует UUID; в песочнице для каждого нового теста генерируй уникальное значение.
- Платёж без `digestSignatures` сохраняется в начальном статусе и ожидает подписания в Альфа-Бизнес. Для платёжного поручения по собственному счёту можно передать одну или две подписи.
- Партнёрский обработчик вебхука рекомендуется завершать не более чем за 300 мс. Если приходит `4xx`/`5xx`, ответ не получен за пять секунд или соединение не установлено, банк повторяет доставку через 30 секунд, 5 и 30 минут, 1, 3, 6, 12, 24, 48 и 72 часа.
- Дубли вебхуков по выписке нужно определять по `transactionId`, по входящим платежам СБП — по `nspkTransactionId`; на дубликат всё равно возвращай `2xx`.
- Старые версии endpoint’ов поддерживаются от двух до шести месяцев. Переход на новую версию нужно предварительно тестировать в песочнице.
- Сохраняй заголовок ответа `x-traceid`: при обращении в поддержку банк просит передать `X-TraceId` вместе с датой, временем, URI, заголовками и телом запроса.

## Другие сценарии

- [Получить выписку по счёту юридического лица](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchit-vypisku-po-schetu.md)
- [Создать и проконтролировать платёжное поручение](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/sozdat-i-prokontrolirovat-platezhnoe.md)
- [Получать уведомления по операциям](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchat-uvedomleniya-po-operatsiyam.md)

---

Если этого недостаточно — официальная документация: https://developers.alfabank.ru/products/alfa-api/documentation
Вся интеграция одним документом: https://mcp-everything.ru/integrations/alfa-bank-api.md