---
url: https://docs.ouvixpro.ai/guia/autenticacao.md
description: >-
  Chaves de API: como criar, enviar como Bearer token, escopo por unidade,
  rotação e revogação.
---

# Autenticação

Toda chamada de dados é autenticada por uma chave de API enviada como *Bearer token* no cabeçalho `Authorization`.

```http
GET /v1/painel?Id_unidade=375&de=2026-10-08&ate=2026-10-08 HTTP/1.1
Host: api.ouvixpro.ai
Authorization: Bearer sk_sky_...
```

## Como obter uma chave

1. Entre no painel com a conta da academia.
2. No menu da conta, abra **Chaves de API**.
3. Clique em **Nova chave**, dê um nome que identifique quem vai usá-la (por exemplo, `ERP financeiro`) e confirme.
4. Copie o valor exibido. Ele aparece **uma única vez**: a plataforma guarda apenas um *hash* e não consegue mostrá-lo de novo.

Se perder a chave, revogue-a e crie outra.

## Escopo

Uma chave enxerga **todas as unidades vinculadas à conta que a criou**, e nada além delas. A unidade desejada é informada em cada chamada pelo parâmetro `Id_unidade`.

* Uma unidade nova, ao ser vinculada à conta, passa a valer nas chaves já existentes.
* Um `Id_unidade` de outra academia responde `403 unidade_negada`.
* Chaves são somente leitura: a API não altera dados.

## Revogação

Em **Chaves de API**, use **Revogar** na chave desejada. O efeito é imediato: a próxima chamada com ela responde `401 chave_invalida`. Uma conta pode manter até 20 chaves ativas.

## Boas práticas

* Guarde a chave em um cofre de segredos ou em variável de ambiente, nunca no código-fonte nem em repositórios.
* Use uma chave por sistema consumidor. Assim a revogação de uma integração não afeta as outras.
* Envie a chave sempre no cabeçalho `Authorization`. A API não aceita chave na *query string*.
* Chame a API apenas a partir de servidores. Não exponha a chave em aplicações de navegador ou celular.
* Rotacione a chave periodicamente: crie a nova, troque na integração e revogue a antiga.

## Erros relacionados

| HTTP | `code` | Causa |
| --- | --- | --- |
| 401 | `chave_ausente` | Cabeçalho `Authorization: Bearer` não enviado. |
| 401 | `chave_invalida` | Chave inexistente, digitada errado ou revogada. |
| 403 | `unidade_negada` | A chave não tem acesso ao `Id_unidade` informado. |

O formato do corpo de erro está em [Limites e erros](/guia/erros).