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

# Autenticação

> Como funcionam as chaves de API da Croma e o esquema bearer.

## Onde obter uma chave

Crie e administre suas chaves de API em
[platform.usecroma.com](https://platform.usecroma.com). Faça login, abra sua
organização e gere uma chave na seção de chaves de API. A chave
completa é exibida uma única vez ao ser criada, então copie-a para um lugar seguro
antes de sair da página.

<Card title="Crie uma chave de API" icon="key" href="https://platform.usecroma.com">
  Abra a plataforma da Croma para gerar e administrar as chaves da sua
  organização.
</Card>

## Esquema bearer

Envie sua chave no cabeçalho `Authorization` usando o esquema `Bearer`:

```bash theme={"dark"}
Authorization: Bearer croma_live_xxxxxxxxxxxxxxxxxxxx
```

## Apenas chaves com escopo de organização

As chaves da Croma são geradas para uma **organização**, não para um usuário
individual. A API rejeita as chaves pessoais com `401`:

```json theme={"dark"}
{
  "error": {
    "type": "authentication_error",
    "code": "personal_api_key_not_allowed",
    "message": "Personal API keys are not allowed. Use an organization key."
  }
}
```

Isso mantém o uso, os limites de taxa e o faturamento atribuídos à
organização, e não a quem tenha criado a chave.

## Formato da chave

As chaves são emitidas com a marca `croma_<env>_…`. Por exemplo, `croma_live_…`
em produção e `croma_test_…` nos demais ambientes. O prefixo de ambiente
indica de relance a qual implantação uma chave aponta; nunca use uma chave
`test` contra dados de produção nem vice-versa.

<Warning>
  Uma chave concede acesso completo à API da sua organização. Guarde-a como um
  segredo (variável de ambiente ou gerenciador de segredos), nunca a inclua no
  controle de versões e faça a rotação se ela for exposta.
</Warning>

## Falha de autenticação

Toda falha de autenticação retorna um `401` com um envelope
`authentication_error`. O campo `code` indica o que deu errado:

| Código                         | O que significa                                                                             | Como resolver                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `invalid_api_key`              | O cabeçalho `Authorization` está ausente ou malformado, ou a chave foi revogada ou expirou. | Envie uma chave válida como `Authorization: Bearer <key>`, ou emita uma nova.                      |
| `personal_api_key_not_allowed` | Uma chave pessoal foi usada onde só se aceitam chaves de organização.                       | Use uma chave com escopo de organização em [platform.usecroma.com](https://platform.usecroma.com). |

<Card title="Próximo: Limites de taxa" icon="gauge" href="/pt/rate-limits">
  Como as cotas são agrupadas e como são expostas em cada resposta.
</Card>