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

# Autenticação

> Como autenticar requisições usando API keys

# Autenticação

Cada requisição à Business API deve incluir uma API key válida no header `X-API-Key`.

## Obter uma API Key

As API keys são gerenciadas pelo **Dashboard da YaVendio** — não existe um endpoint programático para gerenciamento de keys.

<Steps>
  <Step title="Navegar até configurações de APIs">
    Faça login no [Dashboard da YaVendio](https://ya.onl) e vá para **Configurações → Chaves API**.
  </Step>

  <Step title="Criar uma nova key">
    Clique em **"Criar API Key"**. Atribua um nome descritivo (ex. "Integração ERP").
  </Step>

  <Step title="Copiar sua key">
    A key completa é exibida **apenas uma vez** no momento da criação. Copie-a e armazene-a de forma segura. Depois o dashboard mantém apenas o prefixo (`yv_live_v1_Xk3Rt9pQz...`) para identificação.
  </Step>
</Steps>

## Formato da Key

Uma key tem a forma `yv_live_v1_` seguida de 43 caracteres aleatórios:

```
yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZ
```

<Note>
  O dashboard sempre cria keys do tipo `live`. **Não existe ambiente sandbox**: uma key de
  teste operaria sobre os mesmos dados produtivos, então não há uma versão "segura" da
  credencial para experimentar.
</Note>

## Usar a API Key

Inclua a key em cada requisição através do header `X-API-Key`:

```bash theme={null}
curl -H "X-API-Key: yv_live_v1_sua_api_key" \
  https://api.ya.onl/v1/orders
```

## Escopos

Hoje **todas as API keys possuem acesso completo** a todos os endpoints: o dashboard cria as keys sem escopos atribuídos e ainda não oferece onde escolhê-los.

O modelo de escopos já está implementado na API. Cada endpoint declara o seu — `orders:read`, `products:read`, `products:write`, `conversations:read`, `contacts:read`, `company:read`, `webhooks:read`, `webhooks:write`, `outbound:send`, `outbound:read` — e a página de referência de cada um indica qual corresponde. Se uma key tivesse escopos atribuídos e faltasse o que o endpoint exige, a requisição receberia `403 Forbidden`:

```json 403 Forbidden theme={null}
{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}
```

<Note>
  Enquanto não for possível escolher escopos, trate cada key como uma credencial de acesso total: crie uma por integração e exclua-a quando parar de usá-la.
</Note>

## Estados da Key

As keys visíveis no dashboard possuem dois estados possíveis:

| Estado | Significado |
| - | - |
| **Ativa** | A key é válida e aceita requisições |
| **Revogada** | A key foi desativada e todas as requisições são rejeitadas com 401 |

## Informações no Dashboard

A tabela de API keys no dashboard mostra:

* **Nome** — o nome que você atribuiu ao criar a key
* **Escopo** — hoje sempre mostra "Pedidos e Produtos", porque todas as keys são criadas com acesso completo
* **Status** — Ativa ou Revogada
* **Secret Key** — apenas o prefixo (`yv_live_v1_Xk3Rt9pQz...`)
* **Criada** — quando a key foi criada
* **Último uso** — data da última requisição feita com a key

Para excluir uma key, clique no ícone de lixeira ao lado dela. Esta ação é **irreversível** — qualquer integração usando a key começará a receber erros 401 imediatamente.

## Respostas de Erro

| Status | Quando |
| - | - |
| `401 Unauthorized` | API key ausente, inválida, expirada ou revogada |
| `403 Forbidden` | A key é válida mas não tem o escopo que o endpoint exige. Como hoje as keys são criadas sem escopos, na prática você não deveria ver isso |

```json 401 Unauthorized theme={null}
{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}
```

## Boas Práticas

<Warning>
  Nunca exponha sua API key em código do lado do cliente (JavaScript no navegador, apps móveis). Sempre chame a API pelo seu backend.
</Warning>

* **Use variáveis de ambiente** para armazenar API keys — nunca as escreva diretamente no código fonte.
* **Crie keys separadas** para cada integração ou ambiente (desenvolvimento, staging, produção).
* **Rotacione as keys periodicamente** — exclua a key anterior e crie uma nova pelo dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.