# 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í](https://help.cademi.cloud/pt/conta/acesso-do-suporte-da-cademi.md) 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

1. Abra **Configurações > Chaves de API**.
2. Clique em **Criar chave**.
3. Em **Identificação**, preencha o **Nome**. É assim que a chave aparece na lista e na atividade.
4. Se quiser, preencha a **Finalidade**: onde e para que a chave é usada.
5. 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.
6. Em **Validade**, escolha quando a chave **Expira**: **Nunca**, **30 dias**, **90 dias**, **1 ano** ou **Escolher data**.
7. Clique em **Criar chave**.
8. Na janela **Chave criada**, copie o segredo.
9. 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:

1. O **Status** da chave: suspensa, expirada ou revogada.
2. Se alguém rotacionou o segredo e o prazo do anterior já passou.
3. 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**.