---
title: "Chaves de API e autenticação"
description: "O que é uma chave de API da Qomni, que partes ela tem e por que cada chave vale para um único produto, um único modo e uma única célula."
version: "pt-br"
---

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

# Chaves de API e autenticação

Para chamar a API da Qomni você precisa de uma **chave de API**: uma string
secreta que identifica seu workspace, o produto que você chama e o modo
(teste ou real). Você a envia em cada requisição, no header `Authorization`,
como bearer token:

```http
Authorization: Bearer sk_agents_live_co1_8fK2…Qa91Zx
```

Uma chave vale para um único produto. Com uma chave de Agents você pode chamar
`https://api.qomni.ai/agents/v1` e nada mais. Se a API recebe uma chave de
outro produto, a requisição falha com `401 api_key_wrong_product`.

> **Caution**
>
> As chaves são para o seu servidor. **Nunca as coloque em um navegador nem em um
> app móvel**: qualquer pessoa poderia lê-las. Para falar com um agente a partir de um
> navegador, use uma [sessão em tempo real](#sesiones-en-tiempo-real).

## Por que uma chave por produto

Cada produto da Qomni tem sua própria API, seu próprio consumo e sua própria
fatura. Uma chave por produto te dá três coisas:

- **Acesso mínimo.** Um sistema que cria chamadas recebe uma chave de Agents
  e nada mais. Se essa chave vazar, o atacante não entra na sua conta nem no
  app web.
- **Revogação sem dano colateral.** Você revoga uma chave e as demais continuam
  funcionando.
- **Roteamento sem consultas.** A chave carrega a célula onde seus dados vivem.
  O edge lê o prefixo e envia a requisição ao lugar certo sem buscar
  nada em um banco de dados. [O edge e as células](/pt-br/concepts/edge/) explica isso.

## Anatomia de uma chave

<div class="q-key not-prose">
  <span data-part="type">sk</span>{"_"}<span data-part="product">agents</span>{"_"}<span data-part="mode">live</span>{"_"}<span data-part="cell">co1</span>{"_8fK2…"}<span data-part="check">Qa91Zx</span>
</div>

| Parte | O que significa |
|---|---|
| `sk` | Uma chave secreta (*secret key*). |
| `agents` | O produto para o qual ela serve. Hoje, `agents`. |
| `live` / `test` | Modo real ou [modo de teste](/pt-br/concepts/test-mode/). |
| `co1` | A célula onde vivem os dados do workspace. Você não precisa lê-la. |
| 30 caracteres | O segredo em si. |
| 6 caracteres finais | Um checksum. Uma chave copiada errado é rejeitada antes de chegar a qualquer servidor (`401 api_key_malformed`). |

## Modos: teste e real

O modo não é uma configuração da sua conta: quem decide é a chave que você usa. Uma chave
`sk_agents_test_…` trabalha sobre dados de teste e não disca nenhum número.
Uma chave `sk_agents_live_…` trabalha sobre dados reais e é faturada. Seu
código é o mesmo nos dois casos; você troca a chave e nada mais. Os detalhes
estão em [Modo de teste](/pt-br/concepts/test-mode/).

## Como ela é guardada e exibida

A Qomni guarda só o hash de cada chave, nunca o texto. Por isso a chave
completa é exibida **uma única vez**, ao criá-la. Depois você só verá seu
prefixo e seus últimos quatro caracteres.

Se você perder uma chave, não há como recuperá-la: crie outra e revogue a
anterior. A revogação é imediata: a próxima requisição com essa chave
falha com `401 api_key_invalid`.

## Sessões em tempo real {#sesiones-en-tiempo-real}

Um WebSocket aberto a partir de um navegador não pode enviar headers, então não
pode carregar sua chave. Para isso existe a sessão: seu servidor a cria com sua
chave por REST, recebe uma `url` válida por 60 segundos e a entrega
ao cliente. O cliente abre o socket com essa `url`. A chave nunca sai do
seu servidor. Você faz isso passo a passo em
[Fale com um agente em tempo real](/pt-br/agents/realtime/).

## Limites

- Uma chave não é um usuário: não serve para entrar no app web nem para a
  API de identidade.
- Uma chave não vale em outro produto (`401 api_key_wrong_product`) nem em
  outra célula (`421 wrong_cell`).
- Uma chave de um workspace sem o produto ativo responde
  `403 product_not_active`, mesmo que a chave seja válida.
- Uma chave é de um só modo: para passar à produção você cria uma chave `live`,
  não converte a de teste.

## Veja também

- [Início rápido](/pt-br/get-started/quickstart/): crie uma chave e faça sua primeira chamada.
- [Erros](/pt-br/concepts/errors/): cada código que a autenticação pode devolver.
- [Limites de uso](/pt-br/concepts/rate-limits/): quantas requisições cada chave aceita.

Source: https://docs.qomni.ai/pt-br/concepts/authentication/index.mdx
