# Autenticação e escopos

> Authorization Bearer, chaves rmf_live_ e rmf_test_, escopos por chave e os erros 401 e 403.

Toda chamada leva o cabeçalho `Authorization: Bearer <chave>`. A chave nunca vai na URL.

```http
GET /v1/conta HTTP/1.1
Host: sandbox.api.rmfestrategia.com
Authorization: Bearer rmf_test_...
```

Toda resposta traz `X-Request-Id`. Guarde-o: é o que o suporte pede.

## Uma chave por ambiente

| Prefixo | Onde vale |
|---|---|
| `rmf_test_` | Só no sandbox (`https://sandbox.api.rmfestrategia.com/v1`) |
| `rmf_live_` | Só na produção (`https://api.rmfestrategia.com/v1`) |

Chave no ambiente errado responde 401 [`chave_invalida`](/erros/chave_invalida). A chave é emitida pela equipe da RMF: veja [Como conseguir a chave](/comecar/chave). Cada chave tem escopos, vencimento opcional e lista de IPs opcional, e a conta pode ter até duas chaves ativas por ambiente.

## Escopos

A chave só recebe escopos que o **plano** da conta permite. `conta:ler` e `empresas:ler` entram em todo plano.

| Escopo | Libera |
|---|---|
| `conta:ler` | Ler a conta, o plano, o uso e as chaves |
| `empresas:ler` | Listar e ler empresas |
| `consultas:ler` | Consultas de ICMS e da Reforma |
| `empresas:escrever` | Cadastrar empresas |
| `arquivos:enviar` | Enviar arquivos |
| `arquivos:ler` | Listar e ler arquivos; jobs de leitura |
| `relatorios:criar` | Criar e cancelar relatórios |
| `relatorios:ler` | Ler relatórios, o catálogo, baixar a planilha de resultado; jobs de relatório |
| `webhooks:gerenciar` | Criar, listar, testar e excluir webhooks; reenviar eventos |

Os escopos da captura de documentos (`captura:receita`, `captura:notas`, `captura:dfe`) chegam depois do lançamento, por plano.

## 401 e 403

| Resposta | `codigo` | O que significa | O que fazer |
|---|---|---|---|
| 401 | [`chave_ausente`](/erros/chave_ausente) | Faltou o cabeçalho | Envie `Authorization: Bearer` |
| 401 | [`chave_invalida`](/erros/chave_invalida) | Chave errada, revogada ou de outro ambiente | Confira a chave e o ambiente |
| 401 | [`chave_vencida`](/erros/chave_vencida) | Passou do vencimento | Peça uma nova ao contato comercial |
| 403 | [`escopo_insuficiente`](/erros/escopo_insuficiente) | O plano permite, mas a chave não tem o escopo | Use outra chave, com o escopo certo |
| 403 | [`fora_do_plano`](/erros/fora_do_plano) | O produto não está no plano da conta | Fale com a equipe da RMF; trocar de chave não resolve |

Quando os dois valem, vem `fora_do_plano`.

## O que a minha chave pode chamar

`GET /v1/conta` mostra o tipo da conta (`rede` ou `parceiro`), o ambiente da chave, o nome e o plano: produtos, escopos permitidos e se a planilha de resultado está incluída. Mudança de plano é feita pela equipe da RMF, nunca pela API.

## Guarde a chave com cuidado

- Leia a chave de uma variável de ambiente ou do cofre de segredos. Nunca no código, em log, em mensagem de commit ou em prompt de assistente.
- A chave só vai para hosts `*.rmfestrategia.com`.
- Revogou ou suspeita de vazamento? Peça a revogação à equipe da RMF e use a segunda chave ativa para trocar sem parar.