Registar uma aplicação de parceiro com OAuth e gerir aplicações instaladas

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 é 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.

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

Abra Developer apps

Aceda a Settings e depois selecione Developer apps no grupo Developer.

Inicie uma nova aplicação

Selecione Create app. A caixa de diálogo Create developer app abre-se.

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.

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.

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.

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.

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:

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ê

Se a pessoa não tiver sessão iniciada, o Flowella pede-lhe que inicie sessão primeiro.
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.
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.
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.

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:

{
  "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:

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.

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:

Aceda a Settings e depois selecione Installed apps no grupo Developer.
Selecione Revoke na linha da aplicação.
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.

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.

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

Autenticação, âmbitos, limites de pedidos e erros.

Developer hub

Pedidos de API recentes, guias de início rápido e a API sandbox.

Chaves de API

Acesso mais simples para os seus próprios scripts e integrações.

Referência de webhooks

Reaja a eventos nas organizações que instalam a sua aplicação.

Primeiros passos

Essenciais

Usar a aplicação

Definições

Configuração Meta e WhatsApp

Integração HubSpot

Flows e campanhas

Referência da API

Resolução de problemas

Registro de alterações

Registar uma aplicação de parceiro com OAuth e gerir aplicações instaladas

Como funciona

Antes de começar

Registar uma aplicação

Conduzir um cliente pela autorização

O que o cliente vê

Trocar o código por tokens

Chamar a API

Atualizar um token de acesso

Aceder à sua própria organização

Revogar ou inspecionar um token

Rever e revogar aplicações instaladas

Eliminar uma aplicação

Resolução de problemas

Relacionado

Introdução à API

Developer hub

Chaves de API

Referência de webhooks

​Como funciona

​Antes de começar

​Registar uma aplicação

​Conduzir um cliente pela autorização

​O que o cliente vê

​Trocar o código por tokens

​Chamar a API

​Atualizar um token de acesso

​Aceder à sua própria organização

​Revogar ou inspecionar um token

​Rever e revogar aplicações instaladas

​Eliminar uma aplicação

​Resolução de problemas

​Relacionado

Introdução à API

Developer hub

Chaves de API

Referência de webhooks

Como funciona

Antes de começar

Registar uma aplicação

Conduzir um cliente pela autorização

O que o cliente vê

Trocar o código por tokens

Chamar a API

Atualizar um token de acesso

Aceder à sua própria organização

Revogar ou inspecionar um token

Rever e revogar aplicações instaladas

Eliminar uma aplicação

Resolução de problemas

Relacionado