Uma chave de API permite que um desenvolvedor, ou uma ferramenta que você usa, utilize a Open API do Mateflow para ler e gravar os dados da sua comunidade. Você cria, substitui e revoga chaves de API em Admin → Configurações → Integrações → Acesso à API. Cada chave funciona para uma única comunidade.
Quem pode fazer isso: proprietários e administradores. · Onde: web (console de administração). · Plano: o acesso à API, e quantas requisições de API por dia sua comunidade pode fazer, dependem do seu plano da plataforma.
As chaves de API são por comunidade
As chaves de API pertencem a uma única comunidade, e as requisições feitas com uma chave sempre agem sobre essa comunidade. Para conectar várias comunidades, crie uma chave no console de administração de cada uma.
O painel do criador (app.mateflow.com) não tem chaves de API. As chaves do espaço de trabalho que existiam lá foram substituídas por chaves por comunidade. A página Visão geral de uma comunidade no painel tem um link para a página Integrações dela.
Criar uma chave de API
- Acesse Admin → Configurações → Integrações e abra a aba Acesso à API.
- Clique em Gerar Nova Chave.
- Informe um Nome da Chave que diga para que ela serve, como a ferramenta que vai usá-la e o que ela faz. Os lembretes de expiração citam o nome da chave, então um nome claro mostra a qual integração eles se referem.
- Opcional: ative Somente conteúdo público, por exemplo, se for entregar a chave a terceiros para exibir conteúdo público. Veja Limitar uma chave ao conteúdo público mais abaixo.
- Em Escopos e Permissões, marque só as permissões de que a integração precisa. Veja a próxima seção.
- Em Expira, mantenha Sem expiração ou escolha 30 dias, 90 dias, 180 dias ou 365 dias. O formulário mostra a data e a hora exatas em que a chave deixa de funcionar.
- Opcional: em Lista de IPs Permitidos (Opcional), informe os endereços IP ou os intervalos que podem usar a chave, separados por vírgulas.
- Clique em Gerar Nova Chave.
- Copie a chave em Chave de API Gerada, guarde-a em um lugar seguro e clique em Concluído.
Você só consegue ver a chave completa uma vez. Se perdê-la, crie uma substituta e revogue a chave antiga.
Não é possível alterar as permissões, a expiração nem a configuração Somente conteúdo público de uma chave depois de criá-la. Para alterá-las, crie uma substituta (veja abaixo).
Se a aba Acesso à API mostrar um aviso de upgrade, o seu plano da plataforma não inclui acesso à API. O card Endpoint da API mostra a URL base das requisições e o limite diário de requisições do seu plano, que é zerado às 00:00 UTC.
Escopos (permissões) das chaves de API
As permissões são organizadas em uma linha por tipo de dado, com uma caixa para cada ação. Cada caixa é um escopo:
| Linha | Caixa | O que ela permite |
|---|---|---|
| Comunidade | Ler | Ler o perfil, as configurações e os metadados da comunidade |
| Conteúdo | Ler | Ler publicações, feeds, respostas e resultados de pesquisa |
| Conteúdo | Escrever | Criar, editar e excluir publicações e respostas |
| Mídia | Ler | Ler URLs assinadas de mídias existentes |
| Mídia | Enviar | Solicitar tokens de upload; também cobre a leitura de URLs assinadas de mídia |
| Espaços | Ler | Listar espaços e ler os detalhes dos espaços |
| Membros | Ler | Buscar membros e ler perfis básicos, incluindo os grupos de acesso deles |
| Membros | Convidar | Convidar pessoas por e-mail ou por um link de convite |
Ler em Comunidade já vem marcado quando o formulário abre. Marcar Escrever ou Enviar não marca Ler para você: uma ferramenta que só cria publicações precisa só de Escrever em Conteúdo.
A linha Membros aparece em Acesso sensível. Ler permite que a integração verifique se um endereço de e-mail pertence à sua comunidade. Com Convidar, os convites são enviados em nome do proprietário da comunidade, a menos que a integração indique outra pessoa como remetente, e as pessoas convidadas sempre entram como membros. Os convites pela API podem incluir grupos de acesso. Veja Como funcionam os grupos de acesso.
Chaves mais antigas podem mostrar Todos (legado): elas mantêm só os escopos que existiam quando foram criadas. Crie uma chave nova para usar os escopos mais recentes.
Limitar uma chave ao conteúdo público
Com Somente conteúdo público ativado, a chave só vê o que um visitante não conectado vê. Isso inclui o nome e a descrição dos espaços privados, mas não os dos espaços secretos. Use essa opção em uma chave entregue a terceiros ou em uma ferramenta que só exibe conteúdo público.
Sem essa opção, uma chave pode ler como qualquer membro que a integração indicar, inclusive um administrador, o que dá acesso a espaços privados e pagos. Isso também vale para uma chave só com caixas de Ler marcadas, então somente leitura não significa somente conteúdo público.
Uma chave desse tipo só pode ter Ler em Comunidade, Conteúdo e Espaços. Ao ativar a opção, as outras caixas são desmarcadas e desativadas. As requisições que indicam um membro são recusadas. Na lista Chaves de API, a chave mostra a etiqueta Somente público. As chaves que você já tem não são afetadas.
Quando uma chave de API expira
Uma chave com expiração deixa de funcionar na data e na hora mostradas quando você a criou. As requisições que ainda a usarem são recusadas com um erro que indica ao seu desenvolvedor que a chave expirou, e não que foi revogada ou digitada errado.
Na lista Chaves de API, a coluna Status faz uma contagem regressiva: Expira em 62 dias e, no último dia, em horas. A contagem muda para uma cor de alerta quando faltam 14 dias ou menos. Passe o cursor sobre ela para ver a data e a hora exatas. Depois que a chave expira, o status dela passa a ser Expirada.
Os proprietários e os administradores recebem lembretes 14 dias antes de uma chave expirar, 1 dia antes e quando ela expira. Cada lembrete é uma notificação mais um e-mail e informa quando a chave foi usada pela última vez, para você saber se algo ainda depende dela. Clique na notificação para abrir Acesso à API com a chave destacada. No app Mateflow, a notificação mostra os mesmos detalhes, mas não abre nada. O e-mail é enviado na hora, mesmo que Notificações por e-mail esteja desativada nas suas configurações de notificação ou que seus e-mails cheguem em um resumo Diário ou Semanal. Você só deixa de recebê-lo por e-mail se tiver desativado o e-mail de Avisos do sistema ou definido o E-mail de resumo das notificações (antes chamado Frequência do resumo por e-mail) como Desativado. As chaves revogadas não geram lembretes.
Não é possível prorrogar uma expiração. Para manter uma integração funcionando, substitua a chave antes que ela expire.
Substituir uma chave de API
Substituir gera uma chave nova com as mesmas configurações, para você fazer a troca sem interrupção: você pode ter várias chaves ao mesmo tempo. Essa também é a forma de adicionar uma expiração a uma chave que não tem.
- Na aba Acesso à API, abra o menu de ações da chave e clique em Criar substituta. Quando faltam 14 dias ou menos para uma chave expirar, ou quando ela já expirou, a linha dela também mostra um botão Substituir.
- Criar chave substituta abre com o nome, as permissões, a configuração Somente conteúdo público, a lista de IPs permitidos e a expiração da chave antiga já preenchidos. Altere o que precisar e clique em Gerar Nova Chave. Se a chave antiga tiver uma permissão que este formulário não pode conceder, um aviso "Não copiado" a lista, e a nova chave não a terá.
- Copie a nova chave e coloque-a na sua integração.
- Quando a integração estiver usando a nova chave e ela mostrar um horário em Último Uso, clique em Revogar chave antiga em Próximo passo: aposente a chave antiga e confirme, ou revogue a chave antiga pela lista depois. Até você fazer isso, a chave antiga continua recebendo lembretes de expiração.
As duas chaves têm o mesmo nome. Diferencie-as pelo prefixo da chave, abaixo do nome, e pela data em Criada.
Revogar uma chave de API
- Na aba Acesso à API, encontre a chave em Chaves de API.
- Abra o menu de ações dela e clique em Revogar Chave.
- Confirme. A revogação não pode ser desfeita, e qualquer ferramenta que use a chave para de funcionar.
A lista mostra o Status (Ativa, Expirada ou Revogada) e a data de Último Uso de cada chave. As requisições da API não aparecem em Logs de Entrega, então é pelo Último Uso que você confere se uma chave ainda está em uso. Desconectar o Slack, o Discord ou o Zapier não revoga nenhuma chave de API. A criação e a revogação de chaves ficam registradas em Admin → Configurações → Log de Auditoria, em Integrações.
Manter as chaves de API seguras
- Mantenha as chaves de API em um servidor, não em um site ou app que outras pessoas possam baixar, e envie as requisições por HTTPS.
- Dê a cada ferramenta a sua própria chave, só com os escopos de que ela precisa, para poder revogar uma sem quebrar as outras.
- Ative Somente conteúdo público em uma chave que só exibe conteúdo público, principalmente se for entregue a terceiros.
- Defina uma expiração e substitua as chaves periodicamente, para que uma chave que vaze sem você saber pare de funcionar sozinha.
- Adicione uma Lista de IPs Permitidos quando a ferramenta fizer as chamadas a partir de endereços fixos.
- Revogue uma chave na hora se ela puder ter vazado e depois crie uma substituta.
Onde encontrar a documentação da API
A referência da API cobre os endpoints, os formatos de requisição e de resposta, os escopos, os códigos de erro e exemplos de código. Na aba Acesso à API, o card Documentação para desenvolvedores tem um botão Abrir documentação que leva a mateflow.com/developers. Envie esse link ao seu desenvolvedor. Ele não precisa de uma conta na sua comunidade, e a página fica disponível mesmo que o seu plano não inclua acesso à API.
Artigos relacionados
Este guia foi útil?