# Autenticação e chaves

Como criar uma chave, usá-la nos pedidos e mantê-la segura.

Actualizado em 04/11/2026

## Como autenticar

Envie a chave no cabeçalho `Authorization`, em todos os pedidos:

```text
Authorization: Bearer sandbox_...
```

A API só aceita a chave neste cabeçalho, nunca no endereço. O pedido tem de usar HTTPS.

As operações [`GET /v1/ping`](https://docs.interweb.ao/pt/key-status.md) e [`GET /v1/openapi.json`](https://docs.interweb.ao/pt/key-status.md) não precisam de chave.

## Tipos de chave

| Prefixo | Tipo | O que faz |
|---|---|---|
| `sandbox_` | Sandbox | Lê dados verdadeiros da conta. As escritas são simuladas e nunca cobram. |
| `prod_` | Produção | Lê e altera a sua conta. |

Depois do prefixo vêm 43 caracteres aleatórios. O endereço é o mesmo nos dois modos: é a chave que decide. Veja [Sandbox e Produção](https://docs.interweb.ao/pt/api-rules.md).

## Criar uma chave

As chaves criam-se na página [API](https://www.meu.interweb.ao/api-center.php?language=portuguese&currency=1), dentro do Meu Interweb. Uma chave nunca cria outra chave.

O dono de uma conta com um serviço ou um domínio activo pode criar chaves. Cada conta pode ter até 20 chaves.

Ao criar, escolhe:

- **Nome:** para reconhecer a chave mais tarde.
- **Modo:** Sandbox ou Produção.
- **Permissões:** o que a chave pode fazer. Veja [Permissões](https://docs.interweb.ao/pt/permissions.md).
- **Validade:** 30, 90 ou 365 dias, ou sem validade. A opção predefinida é 90 dias.
- **Lista de IPs:** opcional. Se a preencher, a chave só funciona a partir desses endereços.
- **Limite de gastos:** o valor máximo em 30 dias. Veja [Limite de gastos](https://docs.interweb.ao/pt/permissions.md).

Para confirmar, a página pede:

1. A sua senha actual. Quem entra com Google ou Facebook e não tem senha usável passa só pelo código.
2. Um código de 6 dígitos enviado por e-mail, válido por 10 minutos, com 5 tentativas.

Depois de criada a chave, recebe um e-mail de aviso.

## A chave só se vê uma vez

A chave aparece uma única vez, ao ser criada. Guardamos só o hash da chave e os 4 últimos caracteres, por isso não a conseguimos recuperar. Se a perder, revogue-a e crie outra.

## Quando uma chave deixa de funcionar

| Situação | Resposta | Código |
|---|---|---|
| A chave está em falta ou não é válida | 401 | `unauthorized` |
| A chave foi revogada ou passou da validade | 401 | `unauthorized` |
| Quem criou a chave já não tem acesso à conta | 401 | `unauthorized` |
| A conta não pode usar a API neste momento | 403 | `forbidden` |
| O IP de origem não está na lista da chave | 403 | `ip_not_allowed` |
| A chave não tem a permissão necessária | 403 | `insufficient_scope` |
| A API está desligada | 503 | `disabled` |

## O que uma chave nunca pode fazer

Seja qual for a permissão, uma chave nunca pode:

- criar outra chave;
- mudar a senha ou o e-mail da conta;
- ver dados de cartões.

## Manter a chave segura

- Guarde-a numa variável de ambiente ou num cofre de segredos, nunca no código nem num repositório.
- Use a chave só no seu servidor. Os navegadores só podem chamar a API a partir desta documentação, por isso as páginas do seu site não conseguem usar a chave directamente.
- Crie uma chave para cada programa, com as permissões mínimas e uma validade curta.
- Se a lista de IPs for possível no seu caso, use-a.
- Se a chave ficar exposta, revogue-a logo na página [API](https://www.meu.interweb.ao/api-center.php?language=portuguese&currency=1).

## Ver a chave em uso

A operação [`GET /v1/token`](https://docs.interweb.ao/pt/key-status.md) mostra as permissões, a validade e os limites da chave que fez o pedido. A chave em si nunca é devolvida.