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