
## Начать авторизацию пользователя

`GET /v1/connect/authorize`

Перенаправляет пользователя на страницу согласия Битрикс24 Вайбкод.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `client_id` | string | да | Идентификатор партнёра, полученный при регистрации клиента |
| `redirect_uri` | string | да | URL обратного вызова. Должен совпадать с одним из зарегистрированных у клиента |
| `state` | string | да | Произвольная строка, которая вернётся вместе с кодом. Защита от CSRF |
| `scope` | string | нет | Запрашиваемые права через пробел или запятую: `crm task im`. Если не передать — применяются права, зарегистрированные для клиента. Запрос права за пределами зарегистрированного набора отклоняется |
| `code_challenge` | string | условно | Хеш SHA-256 от `code_verifier` в `base64url` без `=`. Обязателен для публичного клиента или при обязательном PKCE, иначе необязателен |
| `code_challenge_method` | string | условно | `S256`, обязателен вместе с `code_challenge`. Другие методы, пустые значения и метод без хеша отклоняются |
| `portal` | string | нет | Домен портала Битрикс24, который выбрать заранее на странице согласия: `mycompany.bitrix24.ru`. Подсказка, а не выбор портала — см. [Подсказка портала](#подсказка-портала) |
| `operation` | string | нет | Только для клиента в режиме `COMPANY`: `CREATE` — новое подключение, `RECONNECT` — новое согласие администратора без смены секрета, `ROTATE_SECRET` — замена секрета без расширения прав. По умолчанию `CREATE`. Назначение сохраняется на весь поток и при согласии и обмене кода не меняется — см. [Переподключение и ротация секрета](/docs/partner-connect/company#переподключение-и-ротация-секрета) |
| `credential_version` | integer | условно | Текущая версия секрета подключения, от `1`. Обязателен для клиента в режиме `COMPANY` при `operation=ROTATE_SECRET`. Значение берите из поля `data.credential_version` ответа [`GET /v1/connect/company/status`](/docs/partner-connect/company-status) |

Для клиента с секретом PKCE необязателен, если не включён в настройках клиента. Если передать `code_challenge`, платформа сохранит его и потребует соответствующий `code_verifier` при обмене кода. PKCE дополняет `client_secret`, а не заменяет его. Для публичного клиента и при обязательном PKCE хеш нужен всегда.

### Подсказка портала

Если приложение знает, из какого портала Битрикс24 пришёл пользователь, передайте домен этого портала в параметре `portal`. Схему и путь можно не отрезать, регистр не важен.

```
https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=crm%20task&state=abc123random&portal=mycompany.bitrix24.ru
```

- Если пользователь — активный участник указанного портала, этот портал выбран на странице согласия заранее. Иначе портал на странице выбирается так же, как без параметра.
- Пользователь может выбрать другой портал. Ключ выдаётся на тот портал, который пользователь подтвердил, поэтому портал ключа берите из поля `portal.domain` ответа [`POST /v1/connect/token`](/docs/partner-connect/token), а не из своей подсказки.
- Ответ `authorize` от параметра не зависит: приложение не узнаёт, состоит ли пользователь в указанном портале.
- Некорректное значение не вызывает ошибку и не возвращается на `redirect_uri` — вход идёт как без параметра.
- Подсказку учитывает только поток с кодом авторизации для клиентов в режиме `PERSONAL`. Клиенты в режиме `COMPANY` параметр игнорируют, у [входа с устройства](/docs/partner-connect/device-authorize) подсказки портала нет.

## Примеры

Эндпоинт открывается переходом браузера пользователя по ссылке, которую собирает приложение. Ключ API и заголовки `X-Api-Key` и `Authorization` не нужны: приложение называет себя параметром `client_id`.

### curl — OAuth-приложение

Запрос показывает ответ, который получит браузер пользователя: `302` с адресом страницы согласия в заголовке `Location`.

```bash
curl -i "https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=crm%20task&state=abc123random"
```

### JavaScript — OAuth-приложение

```javascript
const state = crypto.randomUUID()
// сохраните state в сессии пользователя, чтобы сверить его на redirect_uri

const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://yourapp.com/callback',
  scope: 'crm task',
  state,
})

const authorizeUrl = `https://vibecode.bitrix24.tech/v1/connect/authorize?${params}`
// отправьте пользователя по authorizeUrl: ссылкой или редиректом со своего сервера
```

Серверный код, который собирает такую ссылку и проверяет `state` при возврате, — в [полном примере](/docs/partner-connect#полный-пример). Ссылку для своего приложения можно собрать и без кода: помощник «Собрать ссылку» в карточке приложения, см. [Регистрация приложения и права](/docs/partner-connect/registration).

## Поля ответа

Ответ — редирект на `redirect_uri` с параметрами в строке запроса:

| Параметр | Тип | Описание |
|----------|-----|----------|
| `code` | string | Одноразовый код авторизации. Приходит после одобрения. Обменивается на ключ через [`POST /v1/connect/token`](/docs/partner-connect/token) |
| `state` | string | Значение `state` из запроса без изменений |
| `error` | string | Код отказа. Приходит вместо `code` |
| `error_description` | string | Машинный код причины отказа. Приходит при [отказе после экрана согласия](#отказ-после-экрана-согласия) и при отказе клиенту в режиме `COMPANY` — см. [Подключение Компании](/docs/partner-connect/company) |

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

**Успешный редирект** после одобрения:

```
https://yourapp.com/callback?code=AUTH_CODE_HERE&state=abc123random
```

**Редирект при отказе** пользователя на странице согласия:

```
https://yourapp.com/callback?error=access_denied&state=abc123random
```

## Пример ответа при ошибке

400 — `client_id` неизвестен либо клиент отключён:

```json
{
  "error": "invalid_client",
  "error_description": "Unknown or inactive client"
}
```

## Ошибки

Ошибки этого эндпоинта приходят тремя разными путями, и обработать нужно все три.

**До того как `redirect_uri` проверен** — обычный ответ `400` с телом RFC 6749. Возвращать пользователя некуда: адрес ещё не подтверждён, редирект на непроверенный URL был бы уязвимостью.

| HTTP | `error` | Условие |
|------|---------|---------|
| 400 | `invalid_request` | Не передан один из `client_id`, `redirect_uri`, `state` |
| 400 | `invalid_client` | `client_id` неизвестен либо клиент отключён |
| 400 | `invalid_request` | `redirect_uri` искажён: не разбирается как URL, содержит фрагмент `#`, логин или пароль. `error_description` — `Redirect URI is malformed` |
| 400 | `invalid_request` | Схема `redirect_uri` не разрешена для его адреса: не `https` у адреса не на localhost, не `http` и не `https` у localhost. `error_description` — `Redirect URI scheme is not allowed for this host` |
| 400 | `invalid_request` | `redirect_uri` не совпадает ни с одним зарегистрированным. `error_description` — `Redirect URI not registered` |

**После того как `redirect_uri` проверен** — редирект обратно на него с параметрами `error` и `state` (RFC 6749 §4.1.2.1). Ваш обработчик `redirect_uri` обязан это разбирать.

| `error` в редиректе | Условие |
|---------------------|---------|
| `invalid_scope` | Запрошено неизвестное право или право за пределами зарегистрированного набора клиента |
| `invalid_scope` | Клиент в режиме `COMPANY` запросил платформенное право `vibe:*`, кроме `vibe:ai` и `vibe:storage`: подключению Компании доступны только эти два платформенных права |
| `invalid_request` | Обязательный PKCE не передан, либо переданы некорректный `code_challenge` или `code_challenge_method`. Поддерживается только `S256` |
| `invalid_request` | Клиент в режиме `COMPANY` передал `operation` не из `CREATE`, `RECONNECT`, `ROTATE_SECRET` |
| `access_denied` с `error_description=CONNECT_COMPANY_NOT_READY` | Клиенту в режиме `COMPANY` отказано до страницы согласия: технические условия подключения не выполнены — клиент отключён либо его настройка для режима `COMPANY` некорректна, запрошенная `operation` ему недоступна, партнёр не подтвердил режим Компании, режим клиента в этот момент меняется либо выдача подключений Компании не готова на платформе. Отказ держится, пока не устранена его причина, поэтому сам по себе повтор его не снимает |
| `access_denied` с `error_description=CONNECT_COMPANY_DISABLED` | Клиенту в режиме `COMPANY` отказано до страницы согласия: подключение Компании недоступно для выбранного пользователя или портала — см. [Подключение Компании](/docs/partner-connect/company) |
| `access_denied` | Пользователь нажал «Отклонить» на странице согласия |
| `access_denied` | Пользователь подтвердил доступ, но ключ выдать не удалось: у портала нет подписки или тарифа, открывающего доступ к Вайбкод, регион не поддерживается либо исчерпан лимит ключей. Машинный код причины приходит в `error_description` |
| `temporarily_unavailable` | Пользователь подтвердил доступ, но выписка ключа не завершилась из-за временной недоступности Битрикс24. Машинный код причины, например `BITRIX_UNAVAILABLE`, приходит в `error_description`. Попытку можно повторить |

```
https://yourapp.com/callback?error=invalid_scope&state=abc123random
```

Остальные отказы клиенту в режиме `COMPANY` приходят так же: `error=access_denied` и машинный код причины в `error_description`. Список этих кодов открыт — см. [Подключение Компании](/docs/partner-connect/company).

**Превышение частоты** — `429` до всякой проверки параметров, поэтому ни редиректа, ни `state` не будет. Лимит: 30 запросов в минуту, считается по паре `client_id` и адрес вызывающего. Действующее значение — в заголовке `x-ratelimit-limit`. Тело приходит в общем конверте API — `{ "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }`, а не в форме RFC 6749, и заголовки `X-RateLimit-*` присутствуют.

Обработать этот путь нужно отдельно, потому что `authorize` открывается **переходом браузера**: пользователь увидит страницу с JSON вместо экрана согласия, на `redirect_uri` не придёт ничего, и приложение не получит обратно свой `state`. Приложение обязано считать такую авторизацию незавершённой по своему таймауту, а не ждать обратного вызова. Значение `Retry-After` называет минимальную паузу.

### Отказ после экрана согласия

Отказ в выдаче ключа наступает уже после того, как пользователь подтвердил доступ. Причину он видит на странице согласия Вайбкод, а в приложение возвращается по кнопке — тогда на `redirect_uri` приходит `error`, `error_description` и исходный `state`:

```
https://yourapp.com/callback?error=access_denied&error_description=MARKETPLACE_REQUIRED&state=abc123random
```

`error_description` несёт машинный код причины, по которому приложение может показать свой экран:

| Код в `error_description` | Что произошло |
|---------------------------|---------------|
| `MARKETPLACE_REQUIRED` | На портале нет активной подписки BitrixGPT + Маркетплейс. Там, где доступ открывает тариф Битрикс24, вместо него приходят `BY_PAID_ONLY`, `KZ_PAID_ONLY` и `UZ_PAID_ONLY` |
| `KEY_LIMIT_REACHED` | Ключ выдать нельзя: исчерпан лимит ключей пользователя или портальный потолок платформы — см. [Лимит ключей](/docs/partner-connect/keys#лимит-ключей) |
| `BITRIX_UNAVAILABLE` | Битрикс24 не ответил во время выписки ключа. Приходит с `error=temporarily_unavailable`, а не `access_denied` |
| `STATE_EXPIRED` | Ссылка согласия истекла до подтверждения — авторизацию начинают заново с `/v1/connect/authorize` |
| `admin_approval_requested` | Пользователь не администратор портала и попросил администраторов разрешить приложению AI — запрос пришёл им в чат бота. Приходит, когда на платформе включено разрешение AI администратором портала. Когда администратор разрешит AI, авторизацию начинают заново с `/v1/connect/authorize` |

Список кодов открыт: приложение должно понимать любой `error_description` как причину отказа и не полагаться на то, что перечень выше исчерпывающий.

При отказе в доступе по денежной причине пользователь видит встроенную карточку оплаты на странице согласия. Действия относятся к выбранному порталу Битрикс24. Для `MARKETPLACE_REQUIRED` карточка предлагает «Узнать подробнее» — открыть описание подписки в новой вкладке, а также активировать пробный период, если он доступен этому порталу. Для `BY_PAID_ONLY`, `KZ_PAID_ONLY`, `UZ_PAID_ONLY` и `INT_TARIFF_REQUIRED` предлагается выбрать тариф Битрикс24. Для `INT_VIBE_PLUS_REQUIRED` — тариф Vibe+. При `INT_TARIFF_REQUIRED` на .com в зависимости от выбранного портала также может предлагаться Vibe+. В модели Vibe+ карточка предлагает активацию пробного периода, если он доступен. Демо-тариф Битрикс24 подключают в самом Битрикс24, если он там доступен.

Пока пользователь не нажмёт кнопку возврата в приложение, на `redirect_uri` ничего не приходит. Возврат после такого отказа передаёт `error=access_denied`, машинный код причины в `error_description` и исходный `state`. `code` и API-ключ не выдаются. После покупки или активации пробного периода вернитесь в приложение и начните авторизацию заново с `/v1/connect/authorize`: одноразовое состояние прежней ссылки уже использовано.

Полный справочник общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Обменять код на API-ключ](/docs/partner-connect/token)
- [Публичный клиент: поток с PKCE](/docs/partner-connect/pkce)
- [Регистрация приложения и права](/docs/partner-connect/registration)
- [Partner Connect](/docs/partner-connect)
