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

# OAuth

> Поток авторизационного кода с PKCE и учётными данными клиента для доступа между серверами.

Twenty реализует OAuth 2.0 с потоком авторизационного кода + PKCE для пользовательских приложений и с учётными данными клиента для доступа между серверами. Клиенты регистрируются динамически по [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — никакой ручной настройки в панели управления.

## Когда использовать OAuth

| Сценарий | Метод аутентификации |
| - | - |
| Внутренние скрипты, автоматизация | [Ключ API](/ru/developers/extend/api#authentication) |
| Внешнее приложение, действующее от имени пользователя | **OAuth — авторизационный код** |
| Между серверами, без контекста пользователя | **OAuth — клиентские учётные данные** |
| Приложение Twenty с расширениями пользовательского интерфейса (UI) | [Приложения](/ru/developers/extend/apps/getting-started/quick-start) (OAuth обрабатывается автоматически) |

## Зарегистрировать клиента

Twenty поддерживает **динамическую регистрацию клиентов** по [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). Ручная настройка не требуется — регистрируйте программно:

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}
```

### 4. Используйте токен доступа

```bash theme={null}
GET /rest/companies
Authorization: Bearer ACCESS_TOKEN
```

### 5. Обновляйте при истечении срока действия

```bash theme={null}
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 theme={null}
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 | Детализированный через области действия |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.