> ## Documentation Index > Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt > Use this file to discover all available pages before exploring further. # Registar uma aplicação de parceiro com OAuth e gerir aplicações instaladas > Registe uma aplicação OAuth, conduza os clientes pelo ecrã de consentimento do Flowella, troque códigos por tokens e reveja ou revogue as aplicações instaladas na sua organização. Uma aplicação OAuth permite que outras organizações Flowella liguem o seu produto à respetiva conta sem partilhar chaves de API. Cada organização aprova a sua aplicação num ecrã de consentimento e pode revogá-la a qualquer momento. Esta página mostra aos parceiros como registar uma aplicação e usar OAuth, e mostra aos clientes como rever e revogar as aplicações que instalaram. Para os seus próprios scripts e integrações, uma [chave de API](https://knowledge.flowella.io/pt/settings/api-keys.md) é mais simples. ## Como funciona O Flowella suporta três tipos de concessão OAuth: código de autorização com PKCE para as organizações dos clientes, credenciais de cliente para a sua própria organização e tokens de atualização. A sequência mostra como um cliente instala a sua aplicação com a concessão por código de autorização. ```mermaid theme={null} sequenceDiagram participant Admin as Administrador do cliente participant App as A sua aplicação participant Flowella App->>Admin: Redireciona para o URL de autorização do Flowella Admin->>Flowella: Abre o URL de autorização Flowella->>Admin: Mostra o ecrã de consentimento Admin->>Flowella: Seleciona Allow access Flowella->>App: Redireciona de volta com um código App->>Flowella: Troca o código e o verificador Flowella->>App: Tokens de acesso e de atualização App->>Flowella: Chama a API com o token de acesso ``` ## Antes de começar * Precisa da função **Owner** ou **Admin** na organização que será proprietária da aplicação. Outras funções veem **Developer apps** no menu, mas a lista não carrega para elas. * A sua aplicação precisa de um endereço de callback (redirect URI) que possa receber o código de autorização. * A sua aplicação tem de enviar um valor `state` e um `code_challenge` PKCE gerado com `S256` em cada pedido de autorização. ## Registar uma aplicação **1. Abra Developer apps** Aceda a **Settings** e depois selecione **Developer apps** no grupo **Developer**. **2. Inicie uma nova aplicação** Selecione **Create app**. A caixa de diálogo **Create developer app** abre-se. **3. Dê um nome à aplicação** Em **App name**, introduza o nome pelo qual os clientes conhecem o seu produto, com até 120 caracteres, por exemplo `Acme CRM connector`. **4. Adicione redirect URIs** Em **Redirect URIs**, introduza cada endereço de callback numa linha própria, até 20. Durante a autorização, o `redirect_uri` que a sua aplicação envia tem de corresponder exatamente a um destes. **5. Escolha os âmbitos** Em **Scopes**, os âmbitos de leitura já vêm marcados. Marque qualquer outro âmbito de que a sua aplicação precise e desmarque os que não precisa. Estes são o máximo que a sua aplicação pode alguma vez pedir. Consulte [Âmbitos](https://knowledge.flowella.io/pt/api-reference/introduction.md#âmbitos). **6. Crie a aplicação e copie o segredo** Selecione **Create app**. A caixa de diálogo **Save your client secret** mostra o client secret, que começa por `flc_`. Selecione **Copy**, guarde o segredo no seu servidor e depois selecione **Done**. > [!WARNING] > > O Flowella mostra o client secret apenas uma vez e não é possível repô-lo. Se o perder, tem de eliminar a aplicação e registar uma nova, e todas as organizações que usam a sua aplicação têm de aprovar a nova. Não pode alterar o nome, os redirect URIs nem os âmbitos de uma aplicação depois de a criar. Para os alterar, registe uma nova aplicação. A lista **Developer apps** mostra o **Name**, o **Client ID** (começa por `floa_`), os **Redirect URIs** e a data **Created** de cada aplicação, com um botão **Delete** em **Actions**. ## Conduzir um cliente pela autorização Envie o navegador do cliente para o endpoint de autorização no anfitrião da aplicação Flowella: ```text theme={null} https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256 ``` | Parâmetro | Obrigatório | Valor | | - | - | - | | `response_type` | Sim | `code` | | `client_id` | Sim | O client ID da sua aplicação. | | `redirect_uri` | Sim | Um dos redirect URIs registados da aplicação, exatamente igual. | | `state` | Sim | Um valor aleatório que a sua aplicação verifica quando o cliente regressa. | | `code_challenge` | Sim | O hash SHA-256 codificado em base64url de um `code_verifier` aleatório que a sua aplicação guarda. | | `code_challenge_method` | Não | `S256`, o único método suportado e o predefinido. | | `scope` | Não | Âmbitos separados por espaços, todos dentro dos âmbitos da aplicação. Sem ele, a aplicação recebe apenas os âmbitos de leitura que lhe são permitidos. | | `publicOrgId` | Não | O número de seis dígitos da organização presente no endereço web do Flowella do cliente. Sem ele, o Flowella usa a organização em que a pessoa está a trabalhar nesse momento. | Se o pedido for inválido, o Flowella mostra um erro em vez do ecrã de consentimento e não redireciona. Isto acontece, por exemplo, quando o `redirect_uri` não corresponde ou um âmbito não é permitido. ### O que o cliente vê 1. Se a pessoa não tiver sessão iniciada, o Flowella pede-lhe que inicie sessão primeiro. 2. A pessoa tem de ser **Owner** ou **Admin** da organização. Qualquer outra pessoa vê o erro `Owner or admin role required to authorize apps`. 3. O ecrã **Authorize app** mostra o seu **Client ID:** e os **Requested scopes:**. Se a sua aplicação não enviou um `scope`, indica **This app will receive its default allowed scopes.** 4. A pessoa seleciona **Allow access** ou **Deny**. **Allow access** envia o navegador para o seu `redirect_uri` com `code` e `state` na query string. O código é válido durante 10 minutos e funciona uma única vez. **Deny** envia o navegador para o seu `redirect_uri` com `error=access_denied`, um `error_description` e o seu `state`. ## Trocar o código por tokens O seu servidor troca o código no endpoint de tokens. Autentique-se com o seu client ID e segredo, através de autenticação HTTP Basic ou como `client_id` e `client_secret` no corpo. O corpo pode ser codificado como formulário ou JSON. ```bash theme={null} curl -X POST "https://app.flowella.io/api/oauth/token" \ -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code="$CODE" \ -d redirect_uri="https://example.com/oauth/callback" \ -d code_verifier="$CODE_VERIFIER" ``` A resposta contém os tokens: ```json theme={null} { "access_token": "fla_xxxxxxxxxxxxxxxx", "token_type": "bearer", "expires_in": 3600, "refresh_token": "flr_xxxxxxxxxxxxxxxx", "scope": "messages:read contacts:read" } ``` | Token | Começa por | Validade | | - | - | - | | Token de acesso | `fla_` | 1 hora | | Token de atualização | `flr_` | 30 dias, e apenas até ser usado uma vez | O endpoint de tokens aceita 30 pedidos por minuto por client ID e endereço IP. Acima disso, devolve `429` com um cabeçalho `Retry-After`. ## Chamar a API Envie o token de acesso como bearer token, exatamente como uma chave de API: ```http theme={null} Authorization: Bearer fla_xxxxxxxxxxxxxxxx ``` O token só funciona para a organização que o aprovou e apenas para os âmbitos concedidos. Um pedido fora desses âmbitos devolve `403 INSUFFICIENT_SCOPE`. Cada token de acesso tem o seu próprio limite de pedidos. Consulte a [introdução à API](https://knowledge.flowella.io/pt/api-reference/introduction.md). > [!NOTE] > > `POST /v1/templates/send` aceita apenas chaves de API e recusa tokens de acesso OAuth com `401`. ### Atualizar um token de acesso Antes de o token de acesso expirar, peça um novo com `grant_type=refresh_token`, o `refresh_token` e a autenticação do seu cliente. A resposta inclui um novo token de acesso e um novo token de atualização, e o token de atualização antigo deixa de funcionar. Se alguém apresentar um token de atualização que já foi usado, o Flowella revoga todos os tokens emitidos a partir dessa autorização e o cliente tem de aprovar novamente a sua aplicação. ### Aceder à sua própria organização Para chamar a API em nome da organização proprietária da aplicação, use `grant_type=client_credentials` com a autenticação do seu cliente e um `scope` opcional. Recebe um token de acesso sem token de atualização. A sua aplicação passa então a aparecer em **Installed apps** na sua própria organização. ### Revogar ou inspecionar um token | Endpoint | O que faz | | - | - | | `POST https://app.flowella.io/api/oauth/revoke` | Revoga o `token` que envia, juntamente com todos os tokens emitidos com ele. | | `POST https://app.flowella.io/api/oauth/introspect` | Indica se o `token` está `active`, com o respetivo `scope`, `client_id`, `organization_id` e hora de expiração. | Ambos os endpoints exigem a autenticação do seu cliente. O documento de descoberta em `https://app.flowella.io/.well-known/oauth-authorization-server` lista todos os endpoints e opções suportadas. ## Rever e revogar aplicações instaladas Os clientes gerem as aplicações que aprovaram em **Installed apps**. Precisa da função **Owner** ou **Admin**. A lista mostra: | Coluna | O que mostra | | - | - | | **App** | O nome da aplicação, com o respetivo client ID por baixo. | | **Scopes** | Os âmbitos concedidos à aplicação. | | **Installed** | Quando a aplicação foi aprovada pela primeira vez. | | **Actions** | **Revoke**, ou uma etiqueta **Revoked**. | Para revogar uma aplicação: 1. Aceda a **Settings** e depois selecione **Installed apps** no grupo **Developer**. 2. Selecione **Revoke** na linha da aplicação. 3. Confirme a mensagem **Revoke this install? Existing tokens stop working.** Os tokens da aplicação deixam de funcionar de imediato e ela não os pode atualizar. A linha mantém-se na lista com uma etiqueta **Revoked**. Para dar novamente acesso à aplicação, um Owner ou Admin aprova-a de novo no ecrã de consentimento. > [!NOTE] > > Revogar a sua própria aplicação na sua própria organização não impede a concessão por credenciais de cliente: a aplicação pode pedir um novo token, o que volta a ativar a instalação. Para cortar completamente o acesso da sua própria aplicação, elimine-a em **Developer apps**. ## Eliminar uma aplicação Em **Developer apps**, selecione **Delete** na linha da aplicação e confirme **Delete this app and its tokens?** O Flowella remove a aplicação, a sua instalação em todas as organizações que a aprovaram e todos os seus tokens. Esta ação não pode ser anulada. ## Resolução de problemas > **Could not load developer apps ou Could not load installed apps** > > Apenas Owners e Admins podem ver estes ecrãs. Peça a um Owner ou Admin que faça a gestão da aplicação por si. As funções não podem ser alteradas na aplicação: consulte [Alterar a função de alguém](https://knowledge.flowella.io/pt/settings/team.md#alterar-a-função-de-alguém). > **Redirect URI não corresponde** > > O `redirect_uri` no pedido tem de corresponder exatamente a um dos redirect URIs registados da aplicação, incluindo o esquema, o caminho e qualquer barra final. O mesmo valor tem de ser enviado novamente quando troca o código. Não pode editar os redirect URIs de uma aplicação, por isso registe uma nova aplicação se precisar de outro. > **invalid\_scope** > > Um âmbito pedido está mal escrito ou não é um dos âmbitos da aplicação. Peça apenas os âmbitos que marcou quando registou a aplicação. > **Owner or admin role required to authorize apps** > > A pessoa que está a aprovar a aplicação não é Owner nem Admin da organização. Peça a um Owner ou Admin que conclua a autorização. > **A troca do código falha** > > As mensagens `Authorization code expired` e `Authorization code already used` significam que tem de iniciar novamente a autorização: os códigos duram 10 minutos e funcionam uma única vez. `PKCE verification failed` significa que o `code_verifier` não corresponde ao `code_challenge` que enviou. ## Relacionado > **[Introdução à API](https://knowledge.flowella.io/pt/api-reference/introduction.md)** > > Autenticação, âmbitos, limites de pedidos e erros. > **[Developer hub](https://knowledge.flowella.io/pt/settings/developer-hub.md)** > > Pedidos de API recentes, guias de início rápido e a API sandbox. > **[Chaves de API](https://knowledge.flowella.io/pt/settings/api-keys.md)** > > Acesso mais simples para os seus próprios scripts e integrações. > **[Referência de webhooks](https://knowledge.flowella.io/pt/api-reference/webhooks.md)** > > Reaja a eventos nas organizações que instalam a sua aplicação. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.