snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/extend/oauth.mdx

@@ -0,0 +1,189 @@
+---
+title: OAuth
+icon: key
+description: Поток авторизационного кода с PKCE и учётными данными клиента для доступа между серверами.
+---
+
+Twenty реализует OAuth 2.0 с потоком авторизационного кода + PKCE для пользовательских приложений и с учётными данными клиента для доступа между серверами. Клиенты регистрируются динамически по [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — никакой ручной настройки в панели управления.
+
+## Когда использовать OAuth
+
+| Сценарий                                                           | Метод аутентификации                                                                                   |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Внутренние скрипты, автоматизация                                  | [Ключ API](/l/ru/developers/extend/api#authentication)                                                      |
+| Внешнее приложение, действующее от имени пользователя              | **OAuth — авторизационный код**                                                                        |
+| Между серверами, без контекста пользователя                        | **OAuth — клиентские учётные данные**                                                                  |
+| Приложение Twenty с расширениями пользовательского интерфейса (UI) | [Приложения](/l/ru/developers/extend/apps/getting-started/quick-start) (OAuth обрабатывается автоматически) |
+
+## Зарегистрировать клиента
+
+Twenty поддерживает **динамическую регистрацию клиентов** по [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). Ручная настройка не требуется — регистрируйте программно:
+
+```bash
+POST /oauth/register
+Content-Type: application/json
+
+{
+  "client_name": "My Integration",
+  "redirect_uris": ["https://myapp.com/callback"],
+  "grant_types": ["authorization_code"],
+  "token_endpoint_auth_method": "client_secret_post"
+}
+```
+
+**Ответ:**
+
+```json
+{
+  "client_id": "abc123",
+  "client_secret": "secret456",
+  "client_name": "My Integration",
+  "redirect_uris": ["https://myapp.com/callback"]
+}
+```
+
+<Warning>
+Храните `client_secret` в надёжном месте — позже его нельзя будет получить.
+</Warning>
+
+## Области действия
+
+| Область действия | Доступ                                                      |
+| ---------------- | ----------------------------------------------------------- |
+| `api`            | Полный доступ на чтение/запись к Core и Metadata API        |
+| `profile`        | Чтение информации профиля аутентифицированного пользователя |
+
+Запрашивайте области действия как строку, разделённую пробелами: `scope=api profile`
+
+## Поток авторизационного кода
+
+Используйте этот поток, когда ваше приложение действует от имени пользователя Twenty.
+
+### 1. Перенаправьте пользователя для авторизации
+
+```
+GET /oauth/authorize?
+  client_id=YOUR_CLIENT_ID&
+  response_type=code&
+  redirect_uri=https://myapp.com/callback&
+  scope=api&
+  state=random_state_value&
+  code_challenge=CHALLENGE&
+  code_challenge_method=S256
+```
+
+| Параметр                | Обязательно   | Описание                                                        |
+| ----------------------- | ------------- | --------------------------------------------------------------- |
+| `client_id`             | Да            | Идентификатор вашего зарегистрированного клиента                |
+| `response_type`         | Да            | Должно быть `code`                                              |
+| `redirect_uri`          | Да            | Должен совпадать с зарегистрированным redirect URI              |
+| `scope`                 | Нет           | Области действия, разделённые пробелами (по умолчанию `api`)    |
+| `state`                 | Рекомендуется | Случайная строка для предотвращения CSRF-атак                   |
+| `code_challenge`        | Рекомендуется | Вызов PKCE (хэш SHA-256 от верификатора, в кодировке base64url) |
+| `code_challenge_method` | Рекомендуется | Должно быть `S256` при использовании PKCE                       |
+
+Пользователь видит экран согласия и подтверждает или отклоняет доступ.
+
+### 2. Обработайте обратный вызов
+
+После авторизации Twenty перенаправляет обратно на ваш `redirect_uri`:
+
+```
+https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
+```
+
+Проверьте, что `state` совпадает с отправленным значением.
+
+### 3. Обменяйте код на токены
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=AUTH_CODE&
+redirect_uri=https://myapp.com/callback&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET&
+code_verifier=YOUR_PKCE_VERIFIER
+```
+
+**Ответ:**
+
+```json
+{
+  "access_token": "eyJhbG...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "dGhpcyBpcyBh..."
+}
+```
+
+### 4. Используйте токен доступа
+
+```bash
+GET /rest/companies
+Authorization: Bearer ACCESS_TOKEN
+```
+
+### 5. Обновляйте при истечении срока действия
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&
+refresh_token=YOUR_REFRESH_TOKEN&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET
+```
+
+## Поток клиентских учётных данных
+
+Для интеграций между серверами без участия пользователя:
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET&
+scope=api
+```
+
+Возвращаемый токен имеет доступ на уровне рабочей области и не привязан к конкретному пользователю.
+
+## Обнаружение сервера
+
+Twenty публикует свою конфигурацию OAuth на стандартной конечной точке обнаружения:
+
+```
+GET /.well-known/oauth-authorization-server
+```
+
+Это возвращает все конечные точки, поддерживаемые типы грантов, области действия и возможности — полезно для создания универсальных OAuth-клиентов.
+
+## Сводка конечных точек API
+
+| Конечная точка                            | Назначение                        |
+| ----------------------------------------- | --------------------------------- |
+| `/.well-known/oauth-authorization-server` | Обнаружение метаданных сервера    |
+| `/oauth/register`                         | Динамическая регистрация клиентов |
+| `/oauth/authorize`                        | Авторизация пользователя          |
+| `/oauth/token`                            | Обмен и обновление токена         |
+
+| Среда                       | Базовый URL              |
+| --------------------------- | ------------------------ |
+| **Облако**                  | `https://api.twenty.com` |
+| **Самостоятельный хостинг** | `https://{your-domain}`  |
+
+## OAuth против ключей API
+
+|                                 | API ключи                             | OAuth                                                 |
+| ------------------------------- | ------------------------------------- | ----------------------------------------------------- |
+| **Настройка**                   | Создаются в разделе «Настройки»       | Зарегистрировать клиента, реализовать поток           |
+| **Контекст пользователя**       | Отсутствует (уровень рабочей области) | Права конкретного пользователя                        |
+| **Лучше всего подходит для**    | Скрипты, внутренние инструменты       | Внешние приложения, мультипользовательские интеграции |
+| **Ротация токенов**             | Вручную                               | Автоматическая с помощью refresh-токенов              |
+| **Доступ по областям действия** | Полный доступ к API                   | Детализированный через области действия               |