Skip to main content
A API pública usa dois materiais de autenticação com papéis diferentes: a chave de API e o token. Nunca use um no lugar do outro.

​
O modelo

A chave nunca circula fora da troca por token. Nenhum endpoint de dados aceita a chave diretamente — apresentar uma chave onde um token é esperado devolve 401 INVALID_TOKEN, do mesmo jeito que um token inválido.

​
Trocar a chave por um token

POST /v1/auth/token tem um limite próprio, mais restrito que o resto da API: 10 tentativas por minuto por chave e, separadamente, 10 por minuto por endereço de origem. Passar do limite devolve 429 RATE_LIMITED com a mensagem “Muitas tentativas. Aguarde e tente novamente.” — ver Erros e limites.

​
Usando o token

Todo endpoint de dados espera o token como Bearer token:

​
Renovação

Não existe um endpoint de “refresh” — o token não se renova, se substitui. Peça um novo com POST /v1/auth/token antes do atual expirar (o campo expiresAt da resposta diz exatamente quando). Uma integração de longa duração normalmente troca o token uma vez, guarda em memória, e pede um novo pouco antes de expiresAt, ou reage a um 401 INVALID_TOKEN pedindo um novo na hora. Um token vencido é recusado com 401 INVALID_TOKEN — a resposta nunca diz se o token expirou, foi revogado ou nunca existiu, para não dar pista a quem está tentando adivinhar um token válido.

​
Revogação

A Koolisys revoga uma chave pelas telas internas de gestão. A revogação é imediata e alcança qualquer token já emitido com aquela chave, mesmo que ainda não tivesse expirado — não é preciso esperar os 15 minutos para que o acesso pare de funcionar. Depois de revogada, a chave nunca mais emite um token novo (POST /v1/auth/token passa a devolver 401 INVALID_API_KEY). Peça a revogação à Koolisys sempre que suspeitar que uma chave vazou, ou quando uma integração for desativada.

​
Escopos

Cada chave carrega uma lista de escopos, concedida na criação, e o token emitido a partir dela carrega os mesmos escopos. Um endpoint exige exatamente um escopo: Chamar um endpoint sem o escopo necessário devolve 403 INSUFFICIENT_SCOPE, nomeando o escopo que falta em errors[0].details.requiredScope — nunca silenciosamente um 404 ou 401. Se a sua integração só consulta elegibilidade e abre atendimentos, peça à Koolisys uma chave só com eligibility.read e attendances.write; se ela também sincroniza a base de clientes (ver Clientes e veículos), some customers.write e vehicles.write. O princípio é o menor escopo que a integração precisa.