Ir para o conteúdo
HotLearn
Entrar Testar grátis

Documentação da API

Autorização

O HotLearn usa OAuth 2.1 com código de autorização e PKCE (S256). A pessoa autoriza na tela do HotLearn, o seu aplicativo recebe um código e troca o código pela chave. Nenhuma senha passa pelo seu aplicativo.

O PKCE com S256 é obrigatório para todo aplicativo, com ou sem segredo. Pedido sem code_challenge ou com outro método mostra uma página de erro e não volta ao aplicativo.

Só o dono da conta autoriza, e a conta precisa estar com a assinatura ativa ou no período de teste. Membros veem a tela, mas não conseguem aprovar.

1. Gere o PKCE e o state

Antes de cada autorização, gere três valores e guarde-os no servidor, ligados à pessoa que está conectando (por exemplo, no cache). Com signup=1, a pessoa pode voltar até 2 horas depois com o mesmo state: guarde-os por pelo menos 2 horas (recomendamos 2 h 15 min).

  • code_verifier: texto aleatório de 43 a 128 caracteres;
  • code_challenge: BASE64URL(SHA256(code_verifier)), sem = no fim;
  • state: outro texto aleatório, para conferir na volta.
$verifier  = rtrim(strtr(base64_encode(random_bytes(48)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$state     = bin2hex(random_bytes(16));

2. Mande a pessoa para a tela de autorização

Abra no navegador (redirecionamento ou janela):

https://hotlearn.com.br/oauth/authorize
  ?response_type=code
  &client_id=SEU_CLIENT_ID
  &redirect_uri=https://escola.exemplo.com/hotlearn/retorno
  &scope=account:read catalog:read
  &state=VALOR_DO_STATE
  &code_challenge=VALOR_DO_CHALLENGE
  &code_challenge_method=S256

(Tudo numa linha só, com os valores codificados para URL.)

Parâmetros para aplicativos que atendem vários clientes (como as escolas de um LMS):

  • external_id: o identificador do cliente do seu lado. Recomendamos o id da escola (ou do tenant); um UUID cabe. De 1 a 64 caracteres entre A-Z a-z 0-9 . _ : -; fora disso (inclusive com mais de 64), o pedido é recusado com o código invalid_external_id. Ele nunca é cortado. Cada (conta, aplicativo, external_id) vira uma conexão separada na conta do HotLearn. É opcional para aplicativo de uma conta só (como um assistente de IA), mas obrigatório para aplicativo cadastrado como de várias escolas: sem ele, o pedido é recusado com o código external_id_required;
  • display_name e url: o nome e o endereço desse cliente. A tela mostra "Em nome de {display_name}" só quando o host de url é o mesmo do redirect_uri, para ninguém se apresentar com o nome de outra instituição.

Se a pessoa não estiver logada, o HotLearn pede o login antes, com o aviso "Entre para autorizar {seu aplicativo}".

Quem ainda não tem conta: acrescente signup=1. A pessoa vai direto para o cadastro do HotLearn, com o aviso "Você está assinando por {display_name}". Depois do cadastro e da escolha do plano (ou do teste grátis), ela volta uma vez para esta tela de autorização e segue o fluxo normal. O pedido fica guardado por 2 horas; depois disso, comece de novo. Antes de mandar ao cadastro, o HotLearn confere o PKCE e o external_id: pedido com erro mostra a página de erro já aqui, e não depois do cadastro.

3. Receba a volta

  • Autorizou: https://…/retorno?code=…&state=…. Confira se o state é o mesmo que você guardou.
  • Negou: https://…/retorno?error=access_denied&state=….
  • Pedido inválido (aplicativo desconhecido, redirect_uri fora do cadastro, PKCE faltando ou external_id faltando ou fora do formato): a pessoa não volta ao seu aplicativo. O HotLearn mostra uma página de erro (status 400) com o código: invalid_request, external_id_required ou invalid_external_id. É proteção contra desvio para endereços falsos.

4. Troque o código pela chave

O código vale 10 minutos e só pode ser usado uma vez.

curl -X POST https://hotlearn.com.br/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_SEGREDO \
  -d redirect_uri=https://escola.exemplo.com/hotlearn/retorno \
  -d code_verifier=VALOR_DO_VERIFIER \
  -d code=CODIGO_RECEBIDO

Aplicativo sem segredo (no aparelho da pessoa) não manda client_secret. Resposta:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi…",
  "refresh_token": "def50200a1b2c3…"
}

Guarde as duas chaves criptografadas. Depois confira a conexão com GET /connection.

5. Renove antes de vencer

A chave de acesso vale 1 hora. Renove um pouco antes de vencer, ou quando receber 401 com code = unauthenticated (uma vez só; se continuar, peça para autorizar de novo):

curl -X POST https://hotlearn.com.br/oauth/token \
  -d grant_type=refresh_token \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_SEGREDO \
  -d refresh_token=CHAVE_DE_RENOVACAO
  • A chave de renovação muda a cada uso. Guarde a nova que vem na resposta; a antiga deixa de valer.
  • Nunca use uma chave de renovação antiga de novo. O HotLearn entende isso como chave copiada e desfaz a conexão inteira: a pessoa precisa autorizar de novo. Renove uma vez por vez para cada conexão (uma trava por conexão evita duas renovações ao mesmo tempo).
  • A chave de renovação vence depois de 30 dias sem uso.
  • Com 401 e code = connection_revoked, não renove: a conexão foi desfeita e a pessoa precisa conectar de novo. Renovar depois disso responde no formato do OAuth ({"error": "invalid_grant", …}), e não em problem+json.
  • Não repita chamadas com chave inválida: mais de 300 respostas 401 por minuto do mesmo endereço de rede bloqueiam esse endereço com 429.

6. Desconectar

Pelo aplicativo: mande a chave de renovação para a revogação. Isso desfaz a conexão inteira:

curl -X POST https://hotlearn.com.br/oauth/revoke \
  -d token=CHAVE_DE_RENOVACAO \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_SEGREDO

Pelo HotLearn: o dono clica em Desconectar, em Integrações. As chaves param na hora; a próxima chamada recebe 401 com code = connection_revoked.

Nos dois casos, o que o aplicativo já tirou do HotLearn continua do lado dele.

Conectar de novo

  • Se a conta já tem uma conexão ativa com o mesmo aplicativo, o mesmo external_id e o mesmo redirect_uri exato, o HotLearn aprova sem mostrar a tela e só emite uma chave nova. As chaves antigas continuam valendo, e display_name e url não mudam.
  • Quando o dono aprova na tela (sempre numa conexão nova, ou quando o aplicativo manda prompt=consent), a conexão é substituída: as chaves antigas param e o nome e o endereço são atualizados.
  • Quer trocar ou atualizar a conexão? Mande prompt=consent.

Endereço de volta por padrão

Quando cada cliente do seu aplicativo tem o próprio subdomínio, o cadastro pode usar um padrão: https://*.seudominio.com/hotlearn/retorno. Valem estas regras:

  • * vale um nome antes do domínio (escola.seudominio.com, nunca a.b.seudominio.com);
  • sempre https em produção (http só fora de produção, para testes), sem porta, e com o caminho exatamente igual;
  • se o cliente usa um domínio próprio, faça a volta pelo subdomínio, que continua ativo, e depois leve a pessoa para o domínio dela.

Aplicativo sem conta (vitrine)

Para mostrar a vitrine pública do acervo sem conta conectada, um aplicativo de servidor pode pedir uma chave só dele:

curl -X POST https://hotlearn.com.br/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_SEGREDO \
  -d scope=catalog:public

Essa chave só vale para catalog:public: a lista do acervo (GET /products), as capas e as categorias, só com os campos públicos. A prévia em PDF (GET /products/{id}/preview) precisa de uma chave de conta com catalog:read.

Descoberta automática

Clientes que configuram o OAuth sozinhos (como os clientes MCP) leem os endereços em https://hotlearn.com.br/.well-known/oauth-authorization-server e https://hotlearn.com.br/.well-known/oauth-protected-resource.