Endereço
Autenticação
Toda chamada leva a chave headless da área de membros, inclusive as que já levam o token do aluno. Só os links dedownload_url, que o navegador abre sozinho, dispensam a chave.
POST /auth/login devolve o token do aluno em access_token. Envie-o, junto com a chave, em todas as outras chamadas:
- O token vale por duas semanas. Não há token de renovação: quando ele expira, o aluno entra de novo.
- Uma sessão por aluno. Entrar em outro dispositivo, no seu site ou na área de membros hospedada, encerra a sessão anterior, que passa a responder
session_replaced. Donos e administradores podem ter várias sessões. - Sair encerra só aquele dispositivo.
POST /auth/logoutrevoga o token enviado. - Trocar ou redefinir a senha encerra todos os tokens.
POST /profile/change_passworddevolve um token novo para o dispositivo atual. - Login único: o token de login de 24 horas do aluno, gerado pela API de operador ou presente nos templates de e-mail, é trocado por um token comum em
POST /auth/exchange.
Por que não há token de renovação
Muitas APIs usam um token de acesso curto, de cerca de uma hora, e um token de renovação para estendê-lo sem novo login. A API de membros usa um único token de duas semanas de propósito:- Encerrar uma sessão vale na hora. Sair, trocar a senha ou entrar em outro dispositivo invalida o token na requisição seguinte. Com tokens de renovação, uma sessão encerrada continua respondendo até o token de acesso expirar.
- O site fica mais simples. Não há renovação em segundo plano, disputa entre abas nem um segundo segredo para guardar. O site trata o
401levando o aluno para o login, e só. Isso é o que permite um site estático, sem servidor. - A proteção é a mesma. Um script malicioso na página roubaria o token de renovação junto com o de acesso. O que protege a sessão do aluno é não carregar scripts em que você não confia e nunca renderizar HTML digitado por usuários; veja Segurança.
Listas e paginação
Toda lista devolve o mesmo formato, com os itens emdata:
page, a partir de 1, até chegar a total_pages. O parâmetro limit define quantos itens vêm por página, de 1 a 100; sem ele, vêm 20 itens. As listas que não são paginadas vêm inteiras, com page e total_pages iguais a 1. Algumas listas trazem campos extras ao lado de data, como os totais por tipo em counts na busca.
Limites de requisições
- Cerca de 120 requisições por minuto por endereço IP.
- O login e a recuperação de senha têm limites bem menores, por endereço IP e por e-mail.
- O Assistente de IA aceita 10 mensagens por minuto por aluno.
- As mensagens de contato são 5 por hora por aluno.
429 com o código rate_limited. Espere um pouco antes de tentar de novo.
Envios repetidos
Qualquer chamada que grava algo aceita o cabeçalhoIdempotency-Key, com um valor único por envio, como um UUID. Se a mesma chave chegar de novo com o mesmo corpo em até 24 horas, a API devolve a primeira resposta, com o cabeçalho Idempotent-Replayed, em vez de gravar de novo. Use-o em formulários que criam algo, como comentários, publicações e mensagens de contato.
Só as respostas de sucesso são guardadas: depois de um erro, a mesma chave pode ser usada de novo com o corpo corrigido.
- A mesma chave com um corpo diferente responde
idempotency_key_reused. - Uma repetição que chega enquanto a primeira ainda está em andamento responde
request_in_progress.
Respostas
As chamadas que gravam algo devolvem o que criaram ou mudaram, para o site atualizar a tela pela resposta em vez de buscar tudo de novo. As ações cujo resultado o site já sabe, como seguir uma publicação, marcar a melhor resposta, marcar uma notificação como lida ou aceitar o onboarding, respondem204, sem corpo.
O conteúdo das aulas, o texto do onboarding, as publicações da comunidade e os textos dos quizzes chegam como HTML já renderizado. Os comentários chegam como texto simples. As respostas do Assistente de IA chegam em Markdown, transmitidas como server-sent events, e apontam para aulas com links memberkit://courses/{curso}/lessons/{aula}, que o site converte para os seus próprios endereços.
Arquivos das aulas e certificados trazem um download_url assinado para o aluno, válido por uma hora. É um link comum: o navegador baixa o arquivo sem precisar do token.
Erros
Todo erro chega no mesmo formato:code e mostre a message, que já vem no idioma da área de membros. Informe o request_id ao suporte quando precisar de ajuda com uma chamada.
Erros de validação, com o código validation_failed, trazem também errors, com os problemas de cada campo. Cada um tem um code, como blank, taken ou too_short, para o seu site reagir ou traduzir, e uma message pronta para exibir: