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

# Autenticação

> Como funcionam as chaves de API da Ciarem: vinculadas à organização, plano Scale ou teste gratuito, revogáveis na hora.

## Chaves de API

* As chaves pertencem à sua **organização**, não a uma pessoa. Continuam funcionando se o colega que as criou sair da equipe.
* O segredo começa com `oak_` e é exibido **uma única vez** na criação. A Ciarem guarda apenas um hash: ninguém, nem mesmo a Ciarem, consegue recuperar um segredo perdido.
* Envie-o como token bearer em cada solicitação:

```bash theme={null}
-H "Authorization: Bearer oak_SEU_SEGREDO"
```

## Requisito de plano

A API faz parte do plano **Scale**, e está aberta durante o **teste gratuito** para que você construa e teste sua integração antes de pagar. Uma chave em teste recebe toda a API com um orçamento menor — veja os [limites de uso](/api-reference/errors-limits-pagination). `GET /v1/me` diz em qual você está: `"trial": true` enquanto o teste dura.

Quando uma chave é recusada com `403`, o `detail` diz o que resolve:

| `detail`                | Significado                                                            | O que fazer                                                                                                                                                 |
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scale_plan_required`   | A organização está em um plano ativo abaixo do Scale (Solo ou Growth). | Faça upgrade para o Scale em **Configurações → Cobrança**. A mesma chave volta a funcionar no momento em que o plano muda — sem precisar de uma chave nova. |
| `trial_expired`         | O teste gratuito terminou sem um método de pagamento.                  | Assine o Scale em **Configurações → Cobrança**.                                                                                                             |
| `subscription_required` | A assinatura está cancelada, ou suspensa por falta de pagamento.       | Assine novamente, ou quite o saldo pendente.                                                                                                                |

## Revogação

Revogue uma chave a qualquer momento em **Configurações → Chaves de API**. A revogação é **imediata**: a próxima solicitação com aquele segredo falha com `401`. Administradores podem criar quantas chaves precisarem — uma por integração é um bom hábito, e a data de **último uso** de cada chave ajuda a identificar as que você pode aposentar.

## Boas práticas

* Guarde os segredos no seu gerenciador de segredos ou em variáveis de ambiente — nunca no código nem em aplicações do lado do cliente.
* A API é de servidor para servidor: não a chame de um navegador ou app móvel onde a chave ficaria exposta.
* Faça a rotação criando uma chave nova, migrando sua integração e revogando a antiga em seguida.