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

# Autenticação

> Autentique requisições com uma API key de workspace. Escopo, formato do header e rotação.

A API pública usa **API keys de workspace**. Cada key é vinculada a um único workspace, e todo endpoint roda no contexto desse workspace.

## Criando uma key

1. Entre no Studio e abra o workspace que você quer autenticar.
2. Vá em **Configurações → API keys**.
3. Clique em **Criar API key**. Dê um nome descritivo (ex.: `CLI produção`, `integração Zapier`).
4. Copie a key começando com `gsk_…` — **você não consegue ver de novo** depois de fechar o diálogo. Guarde em um gerenciador de segredos.

<Warning>
  API keys dão acesso total ao workspace ao qual pertencem. Trate como senha: nunca commite no git, nunca cole no Slack ou docs compartilhados.
</Warning>

## Enviando a key

Ambos os formatos são aceitos. Escolha um por projeto e mantenha.

<CodeGroup>
  ```bash Header X-Api-Key (recomendado) theme={null}
  curl https://api.gennia.ai/public/api/v1/agents \
    -H "X-Api-Key: gsk_sua_key_aqui"
  ```

  ```bash Authorization Bearer theme={null}
  curl https://api.gennia.ai/public/api/v1/agents \
    -H "Authorization: Bearer gsk_sua_key_aqui"
  ```
</CodeGroup>

## Erros

| Status | Código no body           | Significado                                                     |
| ------ | ------------------------ | --------------------------------------------------------------- |
| `401`  | `MISSING_API_KEY`        | Sem `X-Api-Key` e sem `Authorization: Bearer …`.                |
| `401`  | `INVALID_API_KEY_FORMAT` | A key não começa com `gsk_` ou tem tamanho errado.              |
| `401`  | `INVALID_API_KEY`        | Key desconhecida, revogada ou pertence a um workspace deletado. |

Um `401` sempre significa **pare e cheque a key** — retry não resolve.

## Rotação

Keys não expiram. Para rotacionar:

1. Crie uma nova key no Studio.
2. Substitua a key na sua integração (env var, secrets manager).
3. Depois de confirmar que a nova key funciona, **revogue** a antiga no Studio.

Não tem janela de overlap — as duas keys funcionam simultaneamente até você revogar. Faça rotações em janelas de baixo tráfego para conseguir confirmar antes de cortar.

## Escopo

Uma key dá **acesso total ao workspace**. Não tem escopo por endpoint nem por recurso. Se você precisa de uma superfície reduzida, rode essa integração como um workspace separado com seus próprios dados e sua própria key.