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

# Autenticação

> Chave de API no header Authorization.

Toda chamada usa uma chave de API no header `Authorization`:

```http theme={null}
Authorization: Bearer ow_live_...
```

* Crie a chave em **Chaves de API**, no console. Ela aparece uma única vez; guardamos só um hash.
* A chave já define a organização, o projeto e o ambiente: `ow_test_` para sandbox e `ow_live_` para produção.
* Cada chave tem escopos. Uma chamada fora dos escopos recebe `403 insufficient_scope`.

| Escopo | Libera |
| - | - |
| `capabilities:execute` | `POST /v1/services` |
| `sessions:write` | Criar sessões e novos links |
| `identity:execute` | `POST /v1/identity/sessions` |
| `sessions:read` | Consultar sessões |
| `reports:write` | Gerar o relatório PDF da sessão |

## Endereços de IP permitidos

Ao criar ou editar a chave, informe os endereços dos seus servidores: IPv4, IPv6 ou faixas CIDR, como `203.0.113.0/24`. Chamadas de outros endereços recebem `403 ip_not_allowed`. Sem nenhum endereço, a chave aceita qualquer origem.

> [!TIP]
>
> Em produção, restrinja os endereços. É o que impede o uso de uma chave vazada fora da sua infraestrutura.

## Validade

Chaves de produção expiram em 1 ano, a não ser que você escolha outra validade (até 730 dias). Chaves de sandbox só expiram se você definir uma validade.

## Rotação sem interrupção

Em **Chaves de API → Rotacionar**, criamos uma chave nova com os mesmos escopos e endereços. A anterior continua funcionando durante o período de transição que você escolher (até 7 dias) e depois expira. Troque a chave nos seus servidores dentro desse período.

## Uso por chave

Em **Chaves de API → Uso**, veja para cada chave e mês: quantas chamadas foram feitas, quantas deram erro, quais serviços foram consultados, de quais endereços de IP vieram, e o valor de cada chamada.

## Alertas de uso

Proprietários e administradores da organização recebem um e-mail quando:

* uma chave que já estava em uso é chamada de um endereço de IP novo;
* uma chave recebe, em uma hora, um volume muito acima da média das 24 horas anteriores.

Se não reconhecer o acesso, revogue ou rotacione a chave e restrinja os endereços.

> [!WARNING]
>
> Use a chave somente no back-end. Nunca a coloque em aplicativos, páginas web ou repositórios. No lado do cliente, use uma [sessão do SDK](https://api-docs.omni-ward.com/sdk/visao-geral.md) criada pelo seu back-end.


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