Autenticação de Aplicações Cliente

Todas as formas de integração com a nossa API são realizadas utilizando o protocolo OAuth 2.0. Independentemente do tipo de aplicação que você está construindo — um serviço backend, uma integração servidor-a-servidor, ou um aplicativo mobile — a autenticação segue esse padrão, através da emissão de um access_token que deve ser enviado em toda requisição subsequente à API.

Nossa API disponibiliza três formas de autenticação (grant types), cada uma adequada a um cenário de integração diferente:

Grant Type	Quando usar
Password	Aplicações de primeira parte, confiáveis, que coletam usuário e senha diretamente.
Client Credentials	Integrações servidor-a-servidor, automações e jobs, sem um usuário associado.
Authorization Code (PKCE)	Aplicações mobile, desktop ou SPAs — qualquer cliente que não consiga armazenar um segredo com segurança.

As seções a seguir detalham cada um desses fluxos.

1.1 Registrando sua aplicação

Antes de utilizar qualquer um dos fluxos abaixo, sua aplicação precisa ser cadastrada por nossa equipe, que fornecerá um client_id e, dependendo do tipo de integração, um client_secret:

Client confidencial (usado em Password e Client Credentials): recebe client_id e client_secret. Adequado apenas para aplicações capazes de armazenar o segredo com segurança — tipicamente serviços backend rodando em ambiente controlado.

Client público (usado em Authorization Code com PKCE): recebe apenas client_id, sem client_secret. Adequado para aplicações que rodam no dispositivo do usuário final (mobile, desktop, navegador), onde qualquer segredo embutido no código pode ser extraído.

⚠️ Se você não tem certeza de qual tipo de client sua aplicação precisa, veja a tabela acima: qualquer aplicação instalada no dispositivo do usuário final (app mobile, app desktop, SPA rodando no navegador) deve usar um client público com Authorization Code + PKCE. Nunca embuta um client_secret nesse tipo de aplicação.

1.2 Password Grant

Use quando sua aplicação coleta as credenciais (usuário e senha) do próprio usuário final diretamente — sem redirecioná-lo a uma tela de login separada. Esse fluxo só deve ser usado por aplicações de confiança total, já que a aplicação tem acesso direto à senha do usuário.

Requisição

POST https://api.bussoladagestao.com.br/v1/oauth/token
Content-Type: application/json

Parâmetro	Descrição
`grant_type`	Valor fixo: `password`
`client_id`	O `client_id` fornecido no cadastro da sua aplicação.
`client_secret`	O `client_secret` fornecido no cadastro da sua aplicação.
`username`	O e-mail (ou nome de usuário) do usuário final.
`password`	A senha do usuário final.

Exemplo com curl:

Resposta de sucesso — `200 OK`

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def502...",
  "usuario": {
    "id": "...",
    "nome": "...",
    "email": "...",
    "empresa": { "..." }
  }
}

O refresh_token retornado permite renovar o access_token sem exigir usuário/senha novamente — veja Renovando o Access Token.

Respostas de erro

Situação	HTTP Status	Observação
`client_id`/`client_secret` inválidos	`401`	Verifique as credenciais da sua aplicação.
`username`/`password` inválidos	`400`/`401`	Usuário ou senha incorretos — não é possível diferenciar qual campo falhou, por segurança.
Campos obrigatórios ausentes	`400`	Confira se todos os parâmetros da tabela acima foram enviados.

1.3 Client Credentials

Use quando a requisição não representa um usuário específico — por exemplo, um job agendado, uma integração entre sistemas, ou um serviço que precisa consultar/gravar dados na API em nome da própria aplicação (não de uma pessoa).

Requisição

POST https://api.bussoladagestao.com.br/v1/oauth/token
Content-Type: application/json

Parâmetro	Descrição
`grant_type`	Valor fixo: `client_credentials`
`client_id`	O `client_id` fornecido no cadastro da sua aplicação.
`client_secret`	O `client_secret` fornecido no cadastro da sua aplicação.

Exemplo com curl:

Resposta de sucesso — `200 OK`

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

Note que não há usuário associado — não existe a chave usuario na resposta, e o access_token gerado representa a aplicação como um todo, não uma pessoa. Consequentemente, este token só deve ser usado contra endpoints da API que não dependem de contexto de usuário (ex: rotas administrativas, integrações de dados, webhooks).

Respostas de erro

Situação	HTTP Status
`client_id`/`client_secret` inválidos	`401`
Campos obrigatórios ausentes	`400`

client_credentials não emite refresh_token — quando o token expirar, basta solicitar um novo repetindo a requisição original.

1.4 Authorization Code com PKCE

Use quando sua aplicação não consegue armazenar um segredo com segurança — o caso de qualquer app mobile, desktop ou single-page application, já que o código roda no dispositivo do usuário e pode ser inspecionado.

PKCE (Proof Key for Code Exchange, RFC 7636) é uma extensão de segurança do fluxo Authorization Code do OAuth2: no lugar de um client_secret fixo, a aplicação gera um segredo descartável e único por login (o code_verifier), de forma que, mesmo que alguém intercepte o authorization code durante o fluxo, não consiga trocá-lo por um access_token sem esse segredo temporário.

Visão geral do fluxo

┌─────────────┐                                    ┌──────────────────┐
│  Seu App    │                                    │   Nossa API      │
└──────┬──────┘                                    └─────────┬────────┘
       │  1. Gera code_verifier e code_challenge             │
       │                                                     │
       │  2. Abre navegador/Custom Tab:                      │
       │     GET /v1/oauth/authorize?...code_challenge=...   │
       ├────────────────────────────────────────────────────►│
       │                                                     │
       │           3. Usuário faz login (na nossa tela)      │
       │                                                     │
       │  4. Redirect de volta com ?code=...&state=...       │
       │◄────────────────────────────────────────────────────┤
       │                                                     │
       │  5. POST /oauth/token (code + code_verifier)        │
       ├────────────────────────────────────────────────────►│
       │                                                     │
       │  6. Retorna access_token                            │
       │◄────────────────────────────────────────────────────┤

Passo 1 — Gerar `code_verifier` e `code_challenge`

code_verifier: string aleatória, gerada com um gerador criptograficamente seguro, entre 43 e 128 caracteres (charset: A-Z, a-z, 0-9, -, ., _, ~).

code_challenge: hash SHA-256 do code_verifier, codificado em base64url (sem padding =).

state: string aleatória (mínimo 128 bits de entropia), usada para proteção contra CSRF.

Recomendação: use uma biblioteca de PKCE já testada para sua plataforma em vez de implementar manualmente — AppAuth-Android / AppAuth-iOS, react-native-app-auth, flutter_appauth. Elas cobrem geração de verifier/challenge, abertura de Custom Tab e validação de state automaticamente.

Guarde o code_verifier e o state localmente (em memória) — você precisará deles no Passo 4.

Abra a URL abaixo em uma Custom Tab do navegador do sistema (Android) ou SFSafariViewController (iOS) — nunca em uma WebView comum embutida no seu app:

GET https://api.bussoladagestao.com.br/v1/oauth/authorize

Parâmetro	Descrição
`client_id`	O `client_id` fornecido no cadastro da sua aplicação.
`redirect_uri`	Uma das URIs de redirecionamento cadastradas para o seu client. Deve corresponder exatamente à uma das cadastradas.
`response_type`	Valor fixo: `code`
`code_challenge`	O `code_challenge` gerado no Passo 1.
`code_challenge_method`	Valor fixo: `S256` (o método `plain` não é suportado).
`state`	O `state` gerado no Passo 1.

Exemplo:

https://api.bussoladagestao.com.br.com/oauth/authorize?
  client_id=e40425cc-0999-4e5a-9c2f-5878072921c5
  &redirect_uri=br.com.suaempresa.app://oauth/callback
  &response_type=code
  &code_challenge=1acb7ed2b29f120cf0db...78f137cd8b7c037dc0264
  &code_challenge_method=S256
  &state=1c71d2d984ab

Passo 3 — Receber o redirect com o `authorization code`

Após o login, o usuário é redirecionado de volta para:

{redirect_uri}?code={authorization_code}&state={state}

Antes de qualquer outra coisa, valide o state: compare com o valor gerado no Passo 1. Se não forem idênticos, rejeite a resposta — isso indica uma possível tentativa de CSRF.

O code recebido tem validade de 10 minutos e é de uso único.

Passo 4 — Trocar o `code` pelo Access Token

POST https://api.bussoladagestao.com.br/v1/oauth/token
Content-Type: application/json

Resposta de sucesso — `200 OK`

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": null,
  "usuario": {
    "id": "...",
    "nome": "...",
    "email": "...",
    "empresa": { "..." }
  }
}

⚠️ refresh_token sempre é null neste fluxo. O access_token tem vida longa e, ao expirar, é necessário repetir o fluxo completo a partir do Passo 2 — não implemente lógica esperando um refresh token.

Respostas de erro — `400 Bad Request`

{
  "error": "CÓDIGO_DO_ERRO",
  "message": "Descrição legível do erro."
}

`error`	Situação
`AUTHORIZATION_CODE_NOT_FOUND`	O `code` enviado não existe ou é inválido.
`AUTHORIZATION_CODE_EXPIRED`	O `code` passou dos 10 minutos de validade.
`AUTHORIZATION_CODE_ALREADY_USED`	O `code` já havia sido trocado por um token anteriormente.
`INVALID_CLIENT_ID`	O `client_id` não confere com o client que gerou o `code`.
`INVALID_REDIRECT_URI`	O `redirect_uri` não é idêntico ao usado no Passo 2.
`INVALID_CODE_VERIFIER`	O `code_verifier` não corresponde ao `code_challenge` original.

1.5 Renovando o Access Token (`refresh_token`)

Disponível apenas para tokens emitidos via Password Grant. Permite obter um novo access_token sem enviar usuário/senha novamente:

POST https://api.bussoladagestao.com.br/v1/oauth/token
Content-Type: application/json

A resposta segue o mesmo formato da requisição original (access_token, novo refresh_token, usuario). Guarde sempre o refresh_token mais recente recebido — o anterior deixa de ser válido após o uso.

1.6 Usando o `access_token`

Independentemente do fluxo utilizado, inclua o token retornado no cabeçalho Authorization de toda requisição subsequente à API:

Authorization: Bearer eyJ0eXAiOiJKV1Qi...

Autenticação de Aplicações Cliente

1.1 Registrando sua aplicação#

1.2 Password Grant#

Requisição#

Resposta de sucesso — 200 OK#

Respostas de erro#

1.3 Client Credentials#

Requisição#

Resposta de sucesso — 200 OK#

Respostas de erro#

1.4 Authorization Code com PKCE#

Visão geral do fluxo#

Passo 1 — Gerar code_verifier e code_challenge#

Passo 2 — Redirecionar o usuário para o login#

Passo 3 — Receber o redirect com o authorization code#

Passo 4 — Trocar o code pelo Access Token#

Resposta de sucesso — 200 OK#

Respostas de erro — 400 Bad Request#

1.5 Renovando o Access Token (refresh_token)#

1.6 Usando o access_token#

1.1 Registrando sua aplicação

1.2 Password Grant

Requisição

Resposta de sucesso — `200 OK`

Respostas de erro

1.3 Client Credentials

Requisição

Resposta de sucesso — `200 OK`

Respostas de erro

1.4 Authorization Code com PKCE

Visão geral do fluxo

Passo 1 — Gerar `code_verifier` e `code_challenge`

Passo 2 — Redirecionar o usuário para o login

Passo 3 — Receber o redirect com o `authorization code`

Passo 4 — Trocar o `code` pelo Access Token

Resposta de sucesso — `200 OK`

Respostas de erro — `400 Bad Request`

1.5 Renovando o Access Token (`refresh_token`)

1.6 Usando o `access_token`