Chaves de API
A credencial que outro sistema usa para ler e mudar dados da sua plataforma pela API: criar a chave, dar permissões, guardar o segredo e revogar.
Uma chave de API é a credencial que um sistema de fora usa para entrar na sua plataforma pela API. Por exemplo: o seu ERP lê alunos e cria matrículas. A chave só faz o que as permissões dela deixam. Em Configurações → Chaves de API você cria as chaves, escolhe o que cada uma pode fazer, acompanha o uso e revoga. Para quem vai programar a integração, a documentação técnica fica em https://cademi.dev/api (botão Documentação).
A ideia em um minuto
Cada chave tem estas partes:
- um nome e uma finalidade, para você reconhecer a chave;
- uma ou mais políticas, que dizem o que a chave pode fazer e onde;
- uma validade, a data em que a chave para de funcionar;
- um segredo, o código que a integração usa para se identificar.
A regra mais importante: o segredo aparece uma vez só, quando a chave é criada. Depois, ninguém consegue ver o segredo de novo. Se ele se perder, gere outro com Rotacionar segredo.
A tela tem duas abas:
- Chaves: as credenciais da API atual.
- API legada: as chaves da API anterior.
A lista de chaves
A lista mostra, para cada chave:
- Nome, com o final do segredo, para você saber qual é qual;
- Permissões;
- Último uso;
- Criada;
- Status: Ativa, Suspensa, Expirada ou Revogada.
O filtro Status recorta a lista. Uma chave que expira nos próximos sete dias mostra o aviso vence com o prazo.
A linha Suporte Cademí é a chave que a Cademí usa para atender os seus chamados. O artigo O acesso do suporte da Cademí explica o que ela faz. Ele mostra também como liberar ou retirar a escrita para o suporte e onde ver o que foi feito.
Criar uma chave
- Abra Configurações → Chaves de API.
- Clique em Criar chave.
- Em Identificação, preencha o Nome. É assim que a chave aparece na lista e na atividade.
- Se quiser, preencha a Finalidade: onde e para que a chave é usada.
- Em Permissões, escolha um modelo em Comece por um modelo. Ou clique em Começar do zero para marcar permissão por permissão.
- Em Validade, escolha quando a chave Expira: Nunca, 30 dias, 90 dias, 1 ano ou Escolher data.
- Clique em Criar chave.
- Na janela Chave criada, copie o segredo.
- Clique em Já copiei.
A tela abre a página da chave. Na janela Chave criada, o bloco Teste a chave traz um comando pronto para conferir que a chave funciona.
Dê à chave só o que a integração precisa. Você pode ajustar as permissões depois. Para uma integração temporária, prefira uma validade.
Os modelos de permissão
| Modelo | O que concede |
|---|---|
| Somente leitura | Lê tudo, não altera nada |
| Gestão de conteúdo | Produtos, aulas, vitrines e banners |
| Gestão de alunos | Alunos, matrículas, tags e progresso |
| Vendas e matrículas | Entregas, eventos de venda e acessos |
| Configurações | Configurações, e-mails, código personalizado e campos do perfil |
| Acesso total | Tudo, menos administradores e chaves |
Como as permissões funcionam
Uma política junta permissões e diz Onde vale:
- Conta toda: a política vale em toda a conta.
- Produtos específicos: a política vale nos produtos escolhidos e em tudo o que está dentro deles: módulos, aulas, provas, certificados, comentários e dúvidas.
Algumas permissões não pertencem a um produto: alunos, entregas, configurações. Se elas entram numa política restrita a produtos, continuam valendo na conta toda. A tela avisa quais são.
Aberta, a política mostra as permissões por área: Alunos, Conteúdo, Vendas, Atendimento, Área do aluno, Configurações, Integração e dados e Administração. Cada recurso tem as colunas Ler, Criar, Editar e Excluir e as Ações especiais. Os botões Só leitura, Tudo e Nada marcam uma área inteira.
Atenção: a área Administração tem o selo Sensível. Uma chave com essas permissões consegue criar administradores e outras chaves. Dê essas permissões só a integrações de confiança total.
Outras marcas da tela:
- Só por administrador: uma chave de API não concede essa permissão. Só um administrador a concede a outro.
- Definida pela API: uma integração definiu o alcance dessa política. Você não a edita nesta tela. Ela continua valendo como está quando você publica as outras.
Uma chave pode ter mais de uma política. Adicionar outra política acrescenta uma. Uma chave sem nenhuma permissão se identifica, mas toda chamada a um recurso é recusada. A tela avisa com Esta chave não tem permissões.
Sem este passo, nada muda. Na página da chave, na aba Permissões, uma mudança só vale depois de Publicar alterações. Cada publicação cria uma versão nova, que vale a partir da próxima chamada. Ver histórico mostra as versões na aba Atividade.
A página de uma chave
Clique na linha para abrir a chave. A página tem três abas.
Visão geral tem quatro painéis:
- Identificação: o nome e a finalidade.
- Segredo: o Segredo atual (só o final dele) e o botão Rotacionar.
- Uso: Último uso (a última chamada nos últimos 30 dias), Ambiente e Criada. O Ambiente é Produção ou Sandbox. A conta define o ambiente quando a chave é criada.
- Validade e limite: Expira e Chamadas por minuto. Vazio segue o padrão da conta. Um limite próprio evita que uma integração gaste o limite das outras.
As mudanças da Visão geral valem com Salvar agora, na barra do rodapé.
Permissões é o editor de políticas, com Publicar alterações.
Atividade mostra tudo o que foi feito com a chave nos últimos 30 dias, com quem fez e de onde: criação, edições, publicações de permissões, rotações, suspensão e revogação. O filtro Tipo separa Criação, Alterações, Segredo e Revogação.
Rotacionar, suspender, revogar
As ações ficam no menu da linha e no cabeçalho da página da chave.
| Ação | O que faz | Volta atrás? |
|---|---|---|
| Rotacionar segredo | Gera um segredo novo. Em O segredo atual para de funcionar em, escolha 1 hora, 24 horas, 3 dias ou 7 dias. Até lá, os dois segredos funcionam, e você troca nas integrações sem parada. O novo aparece uma vez, em Segredo novo | Depois do prazo, o segredo anterior não volta |
| Suspender | A chave é recusada em toda chamada, mas continua cadastrada | Sim, com Reativar |
| Revogar | A chave para de funcionar na hora, em todas as integrações. Ela não pode mais ser alterada. A aba Atividade continua disponível | Não. Para integrar de novo, crie outra chave |
| Remover da lista | Tira da lista uma chave Revogada ou Expirada. O que ela fez continua registrado na atividade da conta | Não |
API legada
A aba API legada guarda o que é da API anterior:
- Token de identificação: o código que identifica a sua plataforma quando uma integração pede.
- Chaves da API anterior: as chaves antigas, com nome, código e data de criação. Elas continuam funcionando nas integrações que já as usam. Não é possível criar chaves novas aqui.
A única ação é excluir. Excluir uma chave interrompe na hora as integrações que a usam. Para uma integração nova, crie uma chave na aba Chaves.
Bom saber
O segredo não volta.
Se a integração perdeu o segredo, a tela não o mostra de novo. Use Rotacionar segredo e troque o segredo na integração dentro do prazo escolhido.
Expirou, parou.
Depois da data de validade, a chave para de funcionar sozinha e aparece como Expirada. Para continuar com a mesma integração, crie uma chave nova.
Sandbox.
O ambiente de uma chave é o da conta em que ela foi criada. Uma conta de testes gera chaves de Sandbox, que não acessam os dados de produção.
Quem pode mexer.
Ver as chaves é uma permissão do administrador. Criar, alterar ou revogar é outra. Um administrador que só vê não consegue criar.
Atividade por 30 dias.
A aba Atividade guarda os últimos 30 dias. O registro geral da conta guarda o que a chave fez, mesmo depois que ela sai da lista.
Perguntas frequentes
A integração parou de funcionar do nada.
Confira três coisas:
- O Status da chave: suspensa, expirada ou revogada.
- Se alguém rotacionou o segredo e o prazo do anterior já passou.
- Se as permissões publicadas cobrem o que a integração faz.
A aba Atividade mostra quem mudou o quê.
Posso dar uma chave que só enxergue um produto?
Pode. Na política, escolha Produtos específicos. Permissões que não são de produto (alunos, entregas, configurações) continuam valendo na conta toda, e a tela avisa quais são.
Qual é a diferença entre suspender e revogar?
Suspender é temporário: a chave fica recusada até você reativar. Revogar é definitivo.
Mudei as permissões e a integração continua sem acesso.
A mudança só vale depois de Publicar alterações, na aba Permissões.
Páginas incorporadas
Uma página sua dentro da área do aluno: a página inicial, a de boas-vindas do primeiro acesso e a página nas aulas, com os dados do aluno que ela recebe.
Webhooks
Avisos automáticos ao seu sistema quando algo acontece na plataforma: eventos, filtros, dados pessoais, histórico de entregas e falhas do destino.