> ## Documentation Index
> Fetch the complete documentation index at: https://docs-koolisys.eixoassistencia.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Chave de longa duração, token de curta duração, e como cada um se comporta.

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

| | Chave de API | Token |
| - | - | - |
| Formato | `kls_` + material aleatório | JWT assinado pela Koolisys |
| Onde é aceito | Só em `POST /v1/auth/token` | Todo endpoint de dados (`/v1/attendances`, `/v1/services`, `/v1/eligibility`, `/v1/customers`, `/v1/vehicles`, `/v1/company`) |
| Validade | Até ser revogada (sem expiração automática, a menos que criada com data de expiração) | 15 minutos (900 segundos) a partir da emissão |
| Como se renova | Não se renova — é revogada e uma nova é criada | Pedindo um novo com a mesma chave, quantas vezes precisar |
| Onde é gerada | Telas internas de gestão da Koolisys | `POST /v1/auth/token` |

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

```bash theme={null}
curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/auth/token \
  --header "Authorization: Bearer kls_EXEMPLO000000000000000000000000000000000000000000000000000000000"
```

```json theme={null}
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJiNmYyYTZiMC02ZTBhLTRjMWEtOWMzYS0yZTZhMmI2YjZhMTAifQ.assinatura-fictícia",
    "tokenType": "Bearer",
    "expiresAt": "2026-08-20T13:15:00.000Z"
  },
  "meta": {},
  "errors": []
}
```

`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](https://docs-koolisys.eixoassistencia.com.br/erros-e-limites.md).

## Usando o token

Todo endpoint de dados espera o token como Bearer token:

```bash theme={null}
curl https://api-koolisys.eixoassistencia.com.br/v1/services \
  --header "Authorization: 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:

| Escopo | Libera |
| - | - |
| `attendances.read` | `GET /v1/attendances`, `GET /v1/attendances/:id` |
| `attendances.write` | `POST /v1/attendances` |
| `services.read` | `GET /v1/services` |
| `eligibility.read` | `GET /v1/eligibility` |
| `customers.read` | `GET /v1/customers`, `GET /v1/customers/:id` |
| `customers.write` | `POST /v1/customers` |
| `vehicles.read` | `GET /v1/vehicles`, `GET /v1/vehicles/:id` |
| `vehicles.write` | `POST /v1/customers/:id/vehicles` |
| `company.read` | `GET /v1/company` |
| `plans.write` | `POST /v1/customers/:id/plans`, `POST /v1/vehicles/:id/plans` |

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](https://docs-koolisys.eixoassistencia.com.br/clientes-e-veiculos.md)), some `customers.write` e `vehicles.write`. O
princípio é o menor escopo que a integração precisa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.