Português
English
Como autenticar
Envie a chave no cabeçalho Authorization, em todos os pedidos:
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 e GET /v1/openapi.json 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.
Criar uma chave
As chaves criam-se na página API, dentro do My MozOut. 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.
- 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.
Para confirmar, a página pede:
- A sua senha actual. Quem entra com Google ou Facebook e não tem senha usável passa só pelo código.
- 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.
Ver a chave em uso
A operação GET /v1/token mostra as permissões, a validade e os limites da chave que fez o pedido. A chave em si nunca é devolvida.