> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar suas requisições na API da Nuvia com uma API Key

Toda requisição à API da Nuvia é autenticada por um **token Bearer** enviado no header
`Authorization`. Esta página explica como autenticar chamadas com uma API Key que você
**já possui**. Para gerar, listar e revogar chaves, veja o [Guia de API Key](/guia-api-key).

## Base URL

```
https://api.nuvia.ai
```

Todas as rotas da API REST usam o prefixo de versão `/v1`. Por exemplo, listar agentes é
`GET https://api.nuvia.ai/v1/agents`.

<Warning>
  A API Key da Nuvia **não** usa um header `X-API-Key` nem um token no formato `sk_...`.
  A chave é enviada como um **token Bearer** no header `Authorization`:

  ```
  Authorization: Bearer <sua-api-key>
  ```

  Enviar a chave em `X-API-Key` resulta em `401` — o servidor simplesmente não lê esse header.
</Warning>

## Duas formas de autenticar

A API aceita dois tipos de identidade **no mesmo header** `Authorization: Bearer`:

* **API Key de empresa** — é o que você usa para **integração programática**. A chave é
  vinculada à sua empresa e aos escopos definidos na criação; pode ter validade opcional
  (`expiresAt`). É o método recomendado para servidores, scripts e integrações.
* **JWT humano** — o token de sessão emitido pelo fluxo de login do aplicativo
  (`POST /v1/auth/login`). Representa um usuário humano, não uma integração. Você não precisa
  dele para consumir a API via API Key.

O servidor identifica automaticamente qual dos dois foi enviado pelo próprio conteúdo do token —
você não sinaliza o tipo em lugar nenhum. Para o resto desta documentação, assumimos o uso de
**API Key de empresa**.

## Autenticando uma requisição

Inclua o header `Authorization` em toda chamada. O exemplo abaixo lista os agentes da sua empresa
(requer o escopo `agents:read`):

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.nuvia.ai/v1/agents \
    -H "Authorization: Bearer $NUVIA_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.nuvia.ai/v1/agents", {
    headers: {
      Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    },
  });

  const data = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.get(
      "https://api.nuvia.ai/v1/agents",
      headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
  )

  data = res.json()
  ```
</CodeGroup>

<Note>
  A API Key é um **token de acesso completo** ao escopo concedido. Trate-a como um segredo:
  guarde em variável de ambiente ou cofre de segredos, nunca no código-fonte nem no controle de
  versão.
</Note>

## Multi-tenant e o header `X-Company-Id`

O tenant (empresa) de uma API Key de empresa é resolvido **pelo próprio token** — você não
precisa informá-lo. O header `X-Company-Id` só é obrigatório para chaves globais de uso interno
e é **ignorado** para API Keys de empresa e para JWT humano. Em resumo: **integrando com uma API
Key de empresa, você não envia `X-Company-Id`.**

## Erros de autenticação

As respostas de erro de autenticação seguem o formato `{ statusCode, message, error }`.

### 401 — não autenticado

Retornado quando o token está ausente, é inválido, expirou ou foi revogado.

```json theme={null}
{
  "statusCode": 401,
  "message": "Autenticação inválida",
  "error": "Unauthorized"
}
```

O campo `message` detalha a causa quando possível — por exemplo `"API Key inválida"`,
`"API Key expirada"`, `"API Key revogada"` ou `"API Key não encontrada"`.

### 403 — sem permissão

Retornado quando o token é válido, mas a API Key **não tem o escopo** necessário para a ação, ou
o endpoint não está disponível para API Keys.

```json theme={null}
{
  "statusCode": 403,
  "message": "API Key não possui o escopo necessário para esta ação",
  "error": "Forbidden"
}
```

Se você recebe `403` em uma chamada que deveria funcionar, verifique se a chave foi criada com o
escopo exigido pelo endpoint. Os escopos são definidos no momento da criação da chave — veja o
[Guia de API Key](/guia-api-key).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de API Key" icon="key" href="/guia-api-key">
    Como gerar, listar e revogar chaves, e quais escopos existem.
  </Card>

  <Card title="Início rápido" icon="rocket" href="/quickstart">
    Faça sua primeira chamada à API em poucos minutos.
  </Card>
</CardGroup>