Token e permissões
Como o token funciona, o que cada permissão libera e como manter a integração segura.
O token é a chave que identifica a sua integração. Ele carrega o que a integração pode fazer (permissões), de onde ela pode chamar (lista de IPs) e até quando (validade). Quem cria, ajusta e desliga tokens é um administrador da escola, em Configurações › API da escola.
Como enviar o token
Em toda chamada, no cabeçalho Authorization:
Authorization: Bearer elms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Todo token começa com
elms_live_, seguido de 40 caracteres. - Nunca na URL nem no corpo. Nesses lugares ele acaba gravado em registros de servidor e no histórico do navegador. A API recusa com
400o token enviado fora do cabeçalho. - Para qualquer problema de credencial — token errado, vencido, revogado, suspenso ou chamado de um IP fora da lista — a resposta é a mesma:
401. É de propósito, para não dar pistas a quem tenta adivinhar. O motivo real fica no histórico do token, que o administrador vê no painel.
Permissões
Marque só o que a integração usa. Nos módulos com três níveis, cada nível inclui os anteriores: quem pode excluir também pode escrever e ler.
| Módulo | Leitura | Escrita | Exclusão |
|---|---|---|---|
| Cursos e categorias | courses.read | courses.write | courses.delete |
| Módulos e aulas | lessons.read | lessons.write | lessons.delete |
| Usuários (alunos e professores) | users.read | users.write | users.delete |
| Turmas | classes.read | classes.write | classes.delete |
| Matrículas | enrollments.read | enrollments.write | enrollments.delete |
| Desempenho (progresso) | performance.read | — | — |
| Certificados | certificates.read | — | — |
| Gamificação (emblemas) | gamification.read | — | — |
| Vendas (pedidos) | sales.read | — | — |
| Assinaturas | subscriptions.read | — | — |
| Relatórios | reports.read | — | — |
Permissões especiais
| Permissão | O que libera |
|---|---|
special.personal_data | Dados pessoais: CPF, telefone e endereço, para ler e gravar. Sem ela, esses campos não aparecem nas respostas e enviá-los gera 403. Dado pessoal fora do LMS passa a ser responsabilidade da escola perante a LGPD. |
special.lesson_content | Conteúdo das aulas: o texto e os links das aulas. Sem ela, as aulas vêm só com título, tipo e situação. |
O que a API nunca faz: criar ou promover administradores, receber senhas, mudar preços e planos ou cobrar. Para conferir as permissões de um token em uso, chame GET /me.
Lista de IPs
Na criação do token você pode informar de quais endereços ele aceita chamadas: um por linha, em IPv4, IPv6 ou faixa (203.0.113.0/24). Em branco, vale qualquer IP.
- A lista é obrigatória para tokens com qualquer permissão de exclusão ou com
special.personal_data. - Uma chamada de IP fora da lista recebe
401, fica no histórico do token e gera um aviso por e-mail para os administradores da escola — quase sempre significa que o token está sendo usado fora do lugar. - Use o IP de saída do servidor que chama a API. Em computador pessoal, o IP da internet pode mudar sem aviso.
Validade, rotação e revogação
- Todo token vence. A validade padrão é de 90 dias e pode chegar a 365. Os administradores recebem aviso por e-mail 14 e 3 dias antes.
- Token parado é desligado. Depois de 60 dias sem uso, os administradores são avisados; aos 180 dias, ele é revogado sozinho.
- Rotacionar gera um token novo com as mesmas permissões. O antigo pode continuar valendo por até 7 dias, para você trocar a integração sem parar o serviço.
- Suspender bloqueia o token na hora e permite reativar depois. Revogar desliga de vez.
- Perdeu o token? Ele não pode ser mostrado de novo, nem pelo suporte. Rotacione e atualize a integração.
Histórico de chamadas
Cada chamada fica registrada no painel, na janela do token: data, rota, resultado, IP, tempo de resposta e os nomes dos campos alterados — nunca os valores. Leituras ficam guardadas por 90 dias e escritas por 365.
Toda resposta traz o cabeçalho X-Request-Id. Guarde-o no log da sua integração e informe-o ao suporte quando precisar de ajuda com uma chamada específica.
