Twenty implementa OAuth 2.0 con código de autorización + PKCE para aplicaciones orientadas al usuario y credenciales de cliente para acceso de servidor a servidor. Los clientes se registran dinámicamente mediante RFC 7591 — sin configuración manual en un panel.
Cuándo usar OAuth
| Escenario | Método de autenticación |
|---|
| Scripts internos, automatización | Clave de API |
| Aplicación externa que actúa en nombre de un usuario | OAuth — Código de autorización |
| De servidor a servidor, sin contexto de usuario | OAuth — Credenciales de cliente |
| Aplicación de Twenty con extensiones de UI | Aplicaciones (OAuth se gestiona automáticamente) |
Registrar un cliente
Twenty admite el registro dinámico de clientes según RFC 7591. No se necesita configuración manual — regístrelo de forma programática:
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"]
}
Almacene el client_secret de forma segura — no se puede recuperar más tarde.
Ámbitos
| Ámbito | Acceso |
|---|
api | Acceso completo de lectura/escritura a las API de Core y Metadata |
profile | Leer la información de perfil del usuario autenticado |
scope=api profile
Flujo de código de autorización
Use este flujo cuando su aplicación actúe en nombre de un usuario de Twenty.
1. Redirija al usuario para autorizar
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
| Parámetro | Obligatorio | Descripción |
|---|
client_id | Sí | Su ID de cliente registrado |
response_type | Sí | Debe ser code |
redirect_uri | Sí | Debe coincidir con un URI de redirección registrado |
scope | No | Ámbitos separados por espacios (valor predeterminado: api) |
state | Recomendado | Cadena aleatoria para evitar ataques CSRF |
code_challenge | Recomendado | Desafío PKCE (hash SHA-256 del verificador, codificado en base64url) |
code_challenge_method | Recomendado | Debe ser S256 al usar PKCE |
2. Gestione el callback
Tras la autorización, Twenty redirige de vuelta a su redirect_uri:
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
state coincida con lo que envió.
3. Intercambie el código por tokens
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. Use el token de acceso
GET /rest/companies
Authorization: Bearer ACCESS_TOKEN
5. Actualice cuando caduque
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
Flujo de credenciales de cliente
Para integraciones de servidor a servidor sin interacción del usuario:
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
Descubrimiento del servidor
Twenty publica su configuración de OAuth en un endpoint de descubrimiento estándar:
GET /.well-known/oauth-authorization-server
Resumen de Puntos de Acceso de API
| Endpoint | Propósito |
|---|
/.well-known/oauth-authorization-server | Descubrimiento de metadatos del servidor |
/oauth/register | Registro dinámico de clientes |
/oauth/authorize | Autorización del usuario |
/oauth/token | Intercambio y renovación de tokens |
| Entorno | URL base |
|---|
| Nube | https://api.twenty.com |
| Autoalojamiento | https://{your-domain} |
OAuth frente a claves de API
| Claves API | OAuth |
|---|
| Configuración | Generar en Ajustes | Registrar un cliente, implementar el flujo |
| Contexto del usuario | Ninguno (a nivel de espacio de trabajo) | Permisos de un usuario específico |
| Ideal para | Scripts, herramientas internas | Aplicaciones externas, integraciones multiusuario |
| Rotación de tokens | Manual | Automática mediante tokens de actualización |
| Acceso con ámbitos | Acceso completo a la API | Granular mediante ámbitos |
