OAuth

Обзор

Twenty реализует OAuth 2.0 с потоком авторизационного кода + PKCE для пользовательских приложений и с учётными данными клиента для доступа между серверами. Клиенты регистрируются динамически по RFC 7591 — никакой ручной настройки в панели управления.

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

Сценарий	Метод аутентификации
Внутренние скрипты, автоматизация	Ключ API
Внешнее приложение, действующее от имени пользователя	OAuth — авторизационный код
Между серверами, без контекста пользователя	OAuth — клиентские учётные данные
Приложение Twenty с расширениями пользовательского интерфейса (UI)	Приложения (OAuth обрабатывается автоматически)

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

Twenty поддерживает динамическую регистрацию клиентов по RFC 7591. Ручная настройка не требуется — регистрируйте программно:

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"
}

Ответ:

{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}

Храните client_secret в надёжном месте — позже его нельзя будет получить.

Области действия

Область действия	Доступ
`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. Обменяйте код на токены

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

Ответ:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}

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

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

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

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

Поток клиентских учётных данных

Для интеграций между серверами без участия пользователя:

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	Детализированный через области действия

Разработчики

Приложения

API

Самостоятельный хостинг

Внести вклад

Библиотека интерфейса

Обзор

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

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

Области действия

Поток авторизационного кода

1. Перенаправьте пользователя для авторизации

2. Обработайте обратный вызов

3. Обменяйте код на токены

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

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

Поток клиентских учётных данных

Обнаружение сервера

Сводка конечных точек API

OAuth против ключей API

​Обзор

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

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

​Области действия

​Поток авторизационного кода

​1. Перенаправьте пользователя для авторизации

​2. Обработайте обратный вызов

​3. Обменяйте код на токены

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

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

​Поток клиентских учётных данных

​Обнаружение сервера

​Сводка конечных точек API

​OAuth против ключей API

Обзор

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

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

Области действия

Поток авторизационного кода

1. Перенаправьте пользователя для авторизации

2. Обработайте обратный вызов

3. Обменяйте код на токены

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

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

Поток клиентских учётных данных

Обнаружение сервера

Сводка конечных точек API

OAuth против ключей API