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

# Autenticação

> Como a API do SULTS autentica cada requisição: token gerado na plataforma, enviado puro no header Authorization, com gestões separadas por versão

Toda requisição à API do SULTS leva um token no header `Authorization`. O token é criado dentro da plataforma por um usuário administrador, e cada versão da API tem a sua própria gestão.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://api.sults.com.br/v1/empresas \
  -H "Authorization: SEU_TOKEN"
```

## O token vai puro, sem Bearer

O valor do header é apenas o token, sem prefixo.

<Warning>
  A API **não usa** o esquema `Bearer`. Envie `Authorization: SEU_TOKEN`, nunca `Authorization: Bearer SEU_TOKEN`. Esse prefixo é uma das causas mais comuns de `401` em quem vem de outras APIs.
</Warning>

Não há login, sessão nem refresh: a API é stateless e valida o token a cada chamada.

## Onde gerar o token da API do SULTS?

O caminho na plataforma é o mesmo para as duas versões:

<Steps>
  <Step title="Entre como administrador">
    O token só pode ser criado por um usuário com permissão de administrador.
  </Step>

  <Step title="Abra Segurança">
    No painel inicial, clique no ícone **Segurança**.
  </Step>

  <Step title="Vá em API">
    No menu lateral esquerdo, clique em **API**.
  </Step>

  <Step title="Escolha a gestão da sua versão">
    A tela tem duas gestões separadas, **Gestão de Tokens v1** e **Gestão de Tokens v2**. Abra a da versão que você vai usar e crie o token.
  </Step>
</Steps>

O passo a passo com os prints de cada tela está na página da sua versão: [criar token na v1](/v1/criar-token) ou [criar token na v2](/v2/criar-token).

## Cada versão tem o seu token

<Warning>
  Tokens da v1 e da v2 **não são intercambiáveis**. Um token gerado na Gestão v2 recebe `401` nos endpoints da v1, e o contrário também vale.
</Warning>

Se as suas chamadas passaram a falhar logo depois de você criar um token novo, confira em qual gestão ele nasceu. É o erro mais frequente de quem integra as duas versões ao mesmo tempo.

## Um token por integração

Crie um token para cada sistema que se conecta ao SULTS e nomeie pelo sistema, por exemplo `ERP Financeiro` ou `BI Comercial`. Assim você revoga um acesso sem derrubar os outros e consegue identificar a origem de cada chamada.

## O que nunca fazer com o token

O token dá acesso aos dados da sua rede inteira. Trate como senha de administrador:

* Nunca coloque o token no front end. Qualquer visitante consegue ler o código da página.
* Nunca versione o token em repositório, mesmo privado. Use variável de ambiente ou cofre de segredos.
* Nunca compartilhe o mesmo token entre sistemas diferentes.

Se um token vazar, exclua na Gestão de Tokens e gere outro. A exclusão vale na hora.

## Por que a API respondeu 401?

A resposta é `401`, com o corpo `{"error": "Acesso não autorizado."}` nas duas versões.

Confira nesta ordem: o token foi copiado por inteiro, o header tem o nome exato `Authorization`, o valor não tem `Bearer`, e o token é da gestão certa para a versão que você está chamando.

O catálogo completo de erros está na sua versão: [erros na v1](/v1/erros) ou [erros na v2](/v2/erros).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Crie o token da v1" icon="key" href="/v1/criar-token">
    O passo a passo da Gestão de Tokens v1, com prints.
  </Card>

  <Card title="Crie o token da v2" icon="key" href="/v2/criar-token">
    O passo a passo da Gestão de Tokens v2, com prints.
  </Card>
</CardGroup>


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