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

# Autenticação

> Como autenticar suas requisições na API da Spedy.

Toda requisição à API da Spedy precisa do header `X-Api-Key` com a chave de
API da sua empresa. Não há OAuth, tokens temporários ou assinatura de
requisição — é uma chave estática por empresa.

```
X-Api-Key: sua-chave-de-api
```

## Chaves e empresas

Cada empresa tem sua própria `X-Api-Key`, que opera e emite notas **apenas**
para aquela empresa.

Quando você assina a Spedy, a primeira empresa — a **empresa titular da
conta** — é criada automaticamente. A chave dela fica disponível no
**backoffice**. Além de emitir as próprias notas, a chave da empresa titular é
a **única** que pode gerenciar empresas (criar, listar, alterar e excluir) via
`/v1/companies`. Veja [Configuração
inicial](/pages/guides/configuracao-inicial).

Se você emite em nome de outras empresas (por exemplo, um SaaS que emite pelos
seus clientes), pode criar empresas adicionais: cada `POST /v1/companies`
(feito com a chave da titular) retorna a `X-Api-Key` da nova empresa no campo
`apiCredentials.apiKey`.

<Warning>
  A chave de uma empresa criada só é exibida **uma vez**, na resposta da
  criação. Em consultas posteriores (`GET /v1/companies/{id}`), o campo
  `apiCredentials.apiKey` vem ofuscado. A chave da empresa titular você
  recupera no backoffice. Guarde as chaves em um cofre de segredos.
</Warning>

## Usando a chave

<CodeGroup>
  ```bash cURL (produção) theme={null}
  curl https://api.spedy.com.br/v1/companies/{id} \
    -H "X-Api-Key: sua-chave-de-api"
  ```

  ```bash cURL (sandbox) theme={null}
  curl https://sandbox-api.spedy.com.br/v1/companies/{id} \
    -H "X-Api-Key: sua-chave-de-api-de-sandbox"
  ```
</CodeGroup>

## Ambientes

Cada ambiente tem sua própria base URL e suas próprias chaves de API — uma
chave de produção não funciona em sandbox, e vice-versa.

| Ambiente | Base URL                              |
| -------- | ------------------------------------- |
| Produção | `https://api.spedy.com.br/v1`         |
| Sandbox  | `https://sandbox-api.spedy.com.br/v1` |

Veja mais detalhes sobre as diferenças entre os ambientes em [Ambiente de
testes](/pages/start/ambiente-de-testes).

<Warning>
  Nunca exponha a `X-Api-Key` em código de front-end, aplicativos mobile ou
  qualquer lugar acessível pelo navegador ou dispositivo do usuário final. A
  chave dá acesso total à conta da empresa — trate-a como uma credencial de
  servidor e faça as chamadas à API da Spedy sempre a partir do seu backend.
</Warning>

## Erros de autenticação

Se a chave for inválida, ausente ou não corresponder ao ambiente usado, a API
responde `403 Forbidden`. Veja a lista completa de códigos de erro em [Erros e
respostas](/pages/start/erros-e-respostas).