amoCRM API v4: Получить токены OAuth и не потерять доступ

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

Для интеграции, которую ставят другие аккаунты: обменять код на токены и вовремя их обновлять.

Отправь пользователя на https://www.amocrm.ru/oauth?client_id=<ID интеграции>&state=&mode=post_message. После согласия amoCRM вернёт code и поддомен аккаунта на redirect_uri. Код живёт 20 минут.
Обменяй код: POST /oauth2/access_token к поддомену аккаунта с client_id, client_secret, grant_type = authorization_code, code и redirect_uri. Сохрани access_token, refresh_token и expires_in.
До истечения access_token обнови пару тем же методом POST /oauth2/access_token с grant_type = refresh_token. Refresh token одноразовый: сразу сохрани новый, иначе пользователю придётся подключать интеграцию заново.
Не обновлённый refresh token истекает через 3 месяца — обновляй токены по расписанию, даже если запросов к аккаунту нет.

# Обмен кода на токены
curl -X POST "https://<поддомен>.amocrm.ru/oauth2/access_token" \
  -H 'Content-Type: application/json' \
  -d '{
        "client_id": "<ID интеграции>",
        "client_secret": "<секрет>",
        "grant_type": "authorization_code",
        "code": "<код из redirect>",
        "redirect_uri": "https://example.ru/amo/callback"
      }'

# Обновление (refresh_token после этого недействителен — сохрани новый)
curl -X POST "https://<поддомен>.amocrm.ru/oauth2/access_token" \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "<ID интеграции>", "client_secret": "<секрет>", "grant_type": "refresh_token", "refresh_token": "<refresh_token>", "redirect_uri": "https://example.ru/amo/callback"}'

Базовые URL

Боевой: https://{subdomain}.amocrm.ru/api/v4/
Авторизация OAuth: https://www.amocrm.ru/oauth

Авторизация

Тип: OAuth 2.0

Два способа:

OAuth 2.0 (authorization code). Пользователь открывает https://www.amocrm.ru/oauth?client_id={Integration ID}&state={state}&mode={popup или post_message}, интеграция получает код (живёт 20 минут) и обменивает его на токены запросом POST /oauth2/access_token к поддомену аккаунта. Refresh token можно использовать только один раз; без использования он истекает через 3 месяца.
Долгосрочный токен — создаётся на вкладке «Ключи» для внешних и приватных интеграций, срок от 1 дня до 5 лет, без refresh token. Повторно посмотреть его нельзя.

Токен передаётся в заголовке Authorization: Bearer {access token}.

Пример запроса токена:

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

{
  "client_id": "xxxx",
  "client_secret": "xxxx",
  "grant_type": "authorization_code",
  "code": "xxxxxxx",
  "redirect_uri": "https://test.test"
}

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

POST /oauth2/access_token — Получение и обновление токенов

Параметр	Где	Тип	Обяз.	Описание
`client_id`	body	string	да	ID интеграции
`client_secret`	body	string	да	Секрет интеграции (для refresh_token — необязателен)
`grant_type`	body	string	да	authorization_code или refresh_token
`code`	body	string	нет	Код авторизации (для authorization_code)
`refresh_token`	body	string	нет	Refresh token (для refresh_token)
`redirect_uri`	body	string	да	Redirect URI интеграции

Нюансы

Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
Успешные ответы приходят с Content-Type: application/hal+json, ошибки — application/problem+json; в запросах с телом указывайте Content-Type: application/json.
Запрос несуществующей сущности по ID возвращает 204 без тела, а не 404.
Refresh token одноразовый: после обновления сохраняйте новый, иначе доступ придётся получать заново.
Ошибки валидации возвращаются массивом validation-errors с request_id и списком errors (code, path, detail).
После окончания подписки запросы на добавление и изменение сразу отклоняются с 402, доступ к данным закрывается через 30 дней.
Повторные превышения лимита приводят к блокировке аккаунта: все запросы получают 403.

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

Если этого недостаточно — официальная документация: https://www.amocrm.ru/developers/content/crm_platform/api-reference Вся интеграция одним документом: https://mcp-everything.ru/integrations/amocrm.md