Chaves de acesso

A chave de acesso identifica a escola e diz o que a integração pode fazer. Ela é criada pelo dono da conta da escola, no painel do EduPay, em Integrações → Tokens de API.

Criar#

1. Em Integrações → Tokens de API, clique em Criar token.
2. Nome: diga onde a chave vai ser usada ("ERP Financeiro", "Site — matrículas"). É por ele que a escola reconhece a chave depois.
3. Permissões: escolha um pacote pronto ou marque uma a uma. Dê só o que a integração precisa. Veja Permissões.
4. Validade: sem validade, 30, 90, 180 ou 365 dias. Vencida, a chave para de funcionar.
5. Copie a chave. Ela começa com edp_ e aparece uma vez só. Se perder, crie outra.

A API pública precisa estar ligada no mesmo lugar (quadro API pública (v1)). Com ela desligada, toda chamada a /api/v1 responde 403 com code api_disabled.

Usar#

Mande a chave no cabeçalho Authorization de toda chamada:

curl https://edupay.estudiosite.com/api/v1/me \
  -H "Authorization: Bearer $EDUPAY_KEY"

• Uma chave por integração. Se uma vazar, só ela precisa ser trocada.
• Guarde como segredo do servidor (variável de ambiente, cofre de senhas). Nunca no código de site ou aplicativo, onde qualquer um consegue ler.
• O painel mostra quando cada chave foi usada pela última vez. Chave parada há muito tempo é candidata a revogar.

Trocar sem derrubar a integração#

Use Rotacionar na linha da chave. O EduPay cria uma chave nova, com o mesmo nome e as mesmas permissões, e a antiga continua valendo por 24 horas. Nesse intervalo:

1. troque a chave na configuração do sistema integrado;
2. confira que as chamadas seguem funcionando (GET /me mostra o nome e o começo da chave em uso);
3. pronto: depois de 24 horas a antiga para sozinha.

Se a chave vazou, não espere as 24 horas: rotacione e, em seguida, revogue a antiga.

Revogar#

Revogar desliga a chave na hora, inclusive uma que está nas 24 horas de convivência depois de rotacionar. Integrações que usam a chave passam a receber 401.

Respostas da autenticação#

As chaves do plugin do Moodle são criadas na mesma tela, com os pacotes do Moodle. Elas seguem funcionando como sempre, com a API pública ligada ou desligada. Veja Integração Moodle.