--- title: OAuth icon: chave description: Fluxo de código de autorização com PKCE e credenciais de cliente para acesso servidor a servidor. --- 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](https://datatracker.ietf.org/doc/html/rfc7591) — sem configuração manual num painel. ## Quando usar OAuth | Cenário | Método de autenticação | | -------------------------------------------------- | --------------------------------------------------------------------------------------- | | Scripts internos, automatização | [Chave de API](/l/pt/developers/extend/api#authentication) | | 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](/l/pt/developers/extend/apps/getting-started) (OAuth é tratado automaticamente) | ## Registar um cliente A Twenty suporta **registo dinâmico de clientes** conforme [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). Sem necessidade de configuração manual — registe programaticamente: ```bash 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" } ``` **Resposta:** ```json { "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 | Solicite escopos como uma cadeia separada por espaços: `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 | O utilizador vê um ecrã de consentimento e aprova ou nega o acesso. ### 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 ``` Verifique se `state` corresponde ao que enviou. ### 3. Troque o código por tokens ```bash 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 ``` **Resposta:** ```json { "access_token": "eyJhbG...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "dGhpcyBpcyBh..." } ``` ### 4. Use o token de acesso ```bash GET /rest/companies Authorization: Bearer ACCESS_TOKEN ``` ### 5. Atualize quando expirar ```bash 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: ```bash 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 ``` O token retornado tem acesso ao nível do espaço de trabalho, não vinculado a nenhum utilizador específico. ## Descoberta do servidor A Twenty publica a sua configuração OAuth num endpoint padrão de descoberta: ``` GET /.well-known/oauth-authorization-server ``` Isto retorna todos os endpoints, tipos de concessão suportados, escopos e capacidades — útil para criar clientes OAuth genéricos. ## 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 |