A Twenty implementa OAuth 2.0 com código de autorização + PKCE para aplicações voltadas ao utilizador e credenciais de cliente para acesso servidor a servidor. Os clientes são registados dinamicamente via RFC 7591 — sem configuração manual num painel.
Quando usar OAuth
| Cenário | Método de autenticação |
|---|
| Scripts internos, automatização | Chave de API |
| Aplicação externa atuando em nome de um utilizador | OAuth — Código de Autorização |
| Servidor a servidor, sem contexto de utilizador | OAuth — Credenciais do Cliente |
| Aplicação Twenty com extensões de UI | Aplicações (OAuth é tratado automaticamente) |
Registar um cliente
A Twenty suporta registo dinâmico de clientes conforme RFC 7591. Sem necessidade de configuração manual — registe programaticamente:
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"]
}
Guarde o client_secret com segurança — não poderá ser recuperado mais tarde.
Escopos
| Escopo | Acesso |
|---|
api | Acesso total de leitura/escrita às APIs Core e Metadata |
perfil | Leia as informações do perfil do utilizador autenticado |
scope=api profile
Fluxo de Código de Autorização
Use este fluxo quando a sua aplicação atuar em nome de um utilizador da Twenty.
1. Redirecione o utilizador 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 | Obrigatório | Descrição |
|---|
client_id | Sim | O seu ID de cliente registado |
response_type | Sim | Deve ser code |
redirect_uri | Sim | Deve corresponder a um URI de redirecionamento registado |
scope | Não | Escopos separados por espaços (predefinido para api) |
estado | Recomendado | Cadeia aleatória para prevenir ataques CSRF |
code_challenge | Recomendado | Desafio PKCE (hash SHA-256 do verificador, codificado em base64url) |
code_challenge_method | Recomendado | Deve ser S256 ao usar PKCE |
2. Trate o callback
Após a autorização, a Twenty redireciona de volta para o seu redirect_uri:
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
state corresponde ao que enviou.
3. Troque o 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 o token de acesso
GET /rest/companies
Authorization: Bearer ACCESS_TOKEN
5. Atualize quando expirar
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
Fluxo de Credenciais do Cliente
Para integrações servidor a servidor sem interação do utilizador:
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
Descoberta do servidor
A Twenty publica a sua configuração OAuth num endpoint padrão de descoberta:
GET /.well-known/oauth-authorization-server
Resumo de endpoints da API
| Endpoint | Finalidade |
|---|
/.well-known/oauth-authorization-server | Descoberta de metadados do servidor |
/oauth/register | Registo dinâmico de cliente |
/oauth/authorize | Autorização do utilizador |
/oauth/token | Troca e atualização de tokens |
| Ambiente | URL base |
|---|
| Nuvem | https://api.twenty.com |
| Auto-hospedado | https://{your-domain} |
OAuth vs Chaves de API
| Chaves API | OAuth |
|---|
| Configuração | Gerar em Configurações | Registar um cliente, implementar o fluxo |
| Contexto do utilizador | Nenhum (nível de espaço de trabalho) | Permissões de um utilizador específico |
| Melhor para | Scripts, ferramentas internas | Aplicações externas, integrações multiutilizador |
| Rotação de tokens | Manual | Automática via tokens de atualização |
| Acesso baseado em escopos | Acesso total à API | Granular por escopos |
