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