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:
Authorization: Bearer sk_agents_live_co1_8fK2…Qa91ZxUma 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.
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 explica isso.
Anatomia de uma chave
| 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. |
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.
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
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.
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: crie uma chave e faça sua primeira chamada.
- Erros: cada código que a autenticação pode devolver.
- Limites de uso: quantas requisições cada chave aceita.