# Autenticação

> Chaves de API, escopos de leitura e gravação, revogação de chaves e como mantê-las seguras.

A API usa chaves de API secretas. Cada chave pertence a um workspace.

## Envie a chave

Coloque a chave no cabeçalho `Authorization` como um token de portador:

```http
GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…
```

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

As chaves sempre começam com `tc_live_`. Não há chaves de teste: experimente em um workspace com dados de amostra, ou leia antes de escrever.

## Crie uma chave

Apenas o **proprietário** do workspace ou um **administrador** pode criar chaves, em **Configurações → API**.

| Configuração      | O que significa                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| Nome              | Seu rótulo, por exemplo, “sincronização de estoque Sage”. Exibido em Configurações e no registro de atividade. |
| Somente leitura   | Apenas solicitações `GET`.                                                                                     |
| Leitura e escrita | Também `PUT /products`, `PUT /customers` e `PATCH /orders/{id}`.                                               |

A chave é mostrada **uma vez**. Armazenamos apenas um hash SHA-256, então ninguém da TradeCatalog pode vê-la novamente. As Configurações mostram os primeiros caracteres (como `tc_live_Xk2m…`) para que você possa diferenciar as chaves.

Um workspace pode ter até **20 chaves ativas**. Dê a cada sistema sua própria chave, para que você possa revogar uma sem afetar as outras.

## Quem pode ter chaves

O workspace precisa de uma dessas para criar chaves:

- uma assinatura ativa
- um teste Pro
- uma conta de pilotagem (acordada com Happy Webs)

Espaços de trabalho de demonstração não podem criar ou usar chaves.

Se a assinatura expirar, você tem 14 dias de graça. Após isso, o espaço de trabalho volta para o plano Free. As chaves existentes ainda podem ler, mas as gravações via API falham com `403 read_only` até que o Pro esteja ativo novamente. Edições de catálogo e pedidos de compradores no app continuam funcionando.

## O que uma chave pode fazer

Uma chave age com as **permissões da pessoa que a criou**, conforme elas são agora. Uma chave criada por um proprietário ou administrador pode ler todos os clientes, os preços de cada cliente, todos os pedidos e o log de atividade. Trate-a como a senha dessa pessoa. Uma chave criada por alguém limitado aos seus clientes ou regiões atribuídos vê apenas esses clientes e seus pedidos, preços e atividade; qualquer outro cliente ou pedido retorna `404`, o mesmo que um que não existe, e alterações de preços retornam `403`.

Se essa pessoa tiver depois um papel mais restrito, a chave também se restringe com ela: uma gravação que o novo papel não permite falha com `403 forbidden`, o mesmo que no app. Se ela sair do espaço de trabalho, a chave deixa de funcionar com `401 key_owner_removed`. Crie uma nova chave a partir de alguém que ainda tenha acesso.

## Último uso e revogação

As configurações mostram quando cada chave foi usada pela última vez (atualizado no máximo uma vez por hora). Escolha **Revogar** para parar imediatamente uma chave. A próxima solicitação com ela recebe `401 unauthorized`. Chaves revogadas não podem ser restauradas.

## Quem os registros são registrados como

As gravações aparecem no log de atividade do espaço de trabalho como `API key “Sage stock sync”`. As mudanças de status dos pedidos são registradas contra a pessoa que criou a chave.

## Mantenha as chaves seguras

- Mantenha as chaves no seu servidor, em variáveis de ambiente ou em um gerenciador de segredos.
- Nunca coloque uma chave em uma página da web, extensão do navegador ou aplicativo móvel. A API não permite solicitações de navegador (CORS) por esse motivo.
- Nunca comite uma chave no git. Se fizer isso, revogue-a e crie uma nova.
- Use uma chave somente leitura sempre que você precisar apenas ler.

## Erros

| Status | Código               | Por quê                                                                                                                                                                   |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `unauthorized`       | Nenhum cabeçalho `Authorization`, um malformado, uma chave desconhecida ou revogada, ou um espaço de trabalho de demonstração. A resposta tem `WWW-Authenticate: Bearer`. |
| 401    | `key_owner_removed`  | A pessoa que criou a chave não tem mais acesso ao espaço de trabalho. Crie uma nova chave.                                                                                |
| 403    | `insufficient_scope` | Uma chave somente leitura tentou gravar.                                                                                                                                  |
| 403    | `forbidden`          | A pessoa que criou a chave não tem permissão para fazer isso (por exemplo, um Visualizador não pode gravar).                                                              |
| 403    | `read_only`          | Gravações via API estão indisponíveis no plano Free.                                                                                                                      |

Veja [Erros](/docs/api/errors) para a lista completa.

**Apps de IA usam um login diferente:** Claude, ChatGPT e outros clientes MCP não usam chaves de API. Cada pessoa entra com seu próprio login através do OAuth. Veja [MCP](/docs/mcp).