Autenticação

AIVAX autentica solicitações de API com chaves de API da conta. AIVAX aceita chaves de API através de:

• Authorization: Bearer <API_KEY>
• Authorization: Basic <BASE64_USERNAME_COLON_API_KEY>
• ?api-key=<API_KEY>

Prefira o cabeçalho Authorization para chamadas servidor‑para‑servidor. Use o parâmetro de consulta apenas quando um cliente ou integração não puder enviar cabeçalhos, pois URLs podem ser registradas por proxies, navegadores e ferramentas de monitoramento.

Tipos de chave de API #

AIVAX tem duas famílias de chaves porque casos de uso de navegador e de servidor têm perfis de risco diferentes. Se seu código roda no seu servidor, use uma chave privada e mantenha‑a fora de bundles de cliente, logs e repositórios públicos. Se seu código roda em um navegador ou outro ambiente onde a chave pode ser inspecionada pelo usuário final, use uma chave pública e limite o fluxo a rotas projetadas para acesso público.

Chaves públicas podem ser usadas para busca semântica RAG, geração de respostas RAG, geração de fala, descrições de mídia, geração de imagens e conclusões de chat. Quando uma chave pública chama conclusões de chat:

• O model deve ser um UUID completo do AI Gateway; chamadas de modelo integrado direto e busca de slug de gateway são desativadas.
• Fontes MCP, funções de protocolo, ferramentas embutidas, Bash, habilidades e opções de sentinela são removidas da solicitação.
• Apenas esses parâmetros de solicitação são aceitos: model, messages, prompt, temperature, top_p, top_k, seed, tools, reasoning_effort, max_completion_tokens, idempotency_key e stream.
• Limites de taxa de solicitações e tokens são aplicados globalmente por chave e por endereço remoto. Veja Public API keys para os valores atuais.

Use chaves privadas para serviços de backend, gerenciamento de contas, listagem de modelos, gerenciamento de coleções, operações em lote e qualquer fluxo de trabalho que precise da superfície completa de ferramentas do gateway.

Para a primeira solicitação do lado do servidor, continue com Getting Started. Se você estiver expondo uma experiência de navegador ou widget para usuários finais, revise Chat Clients antes de decidir se uma chave pública é o limite adequado.

Criar e listar chaves #

Chaves de API pertencem a uma conta e podem ter um rótulo, validade e tipo. Uma chave com duração negativa não expira; chaves expiradas são rejeitadas pela autenticação e posteriormente removidas por jobs de limpeza.

Crie chaves separadas para aplicações separadas. Isso torna a rotação mais segura: se uma integração for comprometida, você pode revogar apenas essa chave em vez de quebrar todos os serviços vinculados à conta. Use rótulos para identificar o proprietário e a aplicação de cada chave, e datas de validade para planejar quando renovar ou substituir.

Reference:

Enviar uma chave com autenticação Bearer #

Para SDKs compatíveis com OpenAI, passe a chave AIVAX como a chave API do SDK e defina a URL base como https://inference.aivax.net/v1.

from openai import OpenAI

client = OpenAI(
    base_url="https://inference.aivax.net/v1",
    api_key="<AIVAX_API_KEY>"
)

Autenticação de hook #

AIVAX pode autenticar solicitações de saída para seus serviços, como workers do AI Gateway e funções de protocolo do lado do servidor.

Esta é a direção inversa da autenticação de API normal. Em uma chamada de API normal, sua aplicação prova que tem permissão para chamar AIVAX enviando uma chave de API. Em um callback de worker ou função de protocolo, AIVAX está chamando seu serviço, então seu serviço precisa de uma forma de verificar que a solicitação realmente veio da configuração de conta que você controla. É para isso que serve X-Request-Nonce.

Se sua conta tem uma chave de hook, AIVAX envia:

X-Request-Nonce: <BCrypt hash>

O nonce é um hash BCrypt derivado da chave de hook da conta. Valide o cabeçalho verificando a chave de hook em texto plano armazenada contra o hash. Se a conta não tem chave de hook, o cabeçalho não é enviado.

Rotacionar a chave de hook invalida os segredos de validação de worker e integração existentes.

Exemplo C# #

using BCrypt.Net;

var nonce = request.Headers["X-Request-Nonce"];
var hookKey = Environment.GetEnvironmentVariable("AIVAX_HOOK_SECRET");

if (nonce is null || hookKey is null)
{
    return Results.Unauthorized();
}

if (!BCrypt.Net.BCrypt.Verify(hookKey, nonce, enhancedEntropy: false))
{
    return Results.Forbid();
}

Exemplo Python #

import os
import bcrypt
from flask import abort, request

nonce = request.headers.get("X-Request-Nonce")
hook_key = os.getenv("AIVAX_HOOK_SECRET")

if nonce is None or hook_key is None:
    abort(401)

if not bcrypt.checkpw(hook_key.encode("utf-8"), nonce.encode("utf-8")):
    abort(403)

Exemplo JavaScript #

import bcrypt from "bcrypt";

const nonce = req.header("X-Request-Nonce");
const hookKey = process.env.AIVAX_HOOK_SECRET;

if (!nonce || !hookKey) {
  return res.sendStatus(401);
}

if (!(await bcrypt.compare(hookKey, nonce))) {
  return res.sendStatus(403);
}