Autenticação¶

O Nodexa usa API keys para autenticar todas as requests. Esta página explica como incluir sua chave nas requests e o que cada escopo permite.

Formato da API Key¶

As API keys do Nodexa usam o prefixo nxk_ seguido de um payload criptografado em base64url:

nxk_eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0...

As chaves são emitidas pelo administrador da sua plataforma Nodexa. São segredos estáticos — trate-as como senhas. Nunca faça commit de API keys no controle de versão nem as exponha em código client-side.

Nunca exponha API keys no client-side

API keys dão acesso às capacidades de IA e aos dados dos usuários da sua plataforma. Use-as sempre a partir de um serviço de backend. Se uma chave for comprometida, fale com seu administrador para revogá-la e emitir uma nova.

Como Passar sua API Key¶

O Nodexa aceita API keys em dois headers HTTP. Ambos são equivalentes — use o que melhor se encaixar no seu fluxo.

Opção 1: header `x-api-key` (recomendado)¶

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Hello" }'

Opção 2: header `Authorization: Bearer`¶

curl https://your-admin.example.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Hello" }'

Compatibilidade com o OpenAI SDK

O OpenAI SDK envia a API key como Authorization: Bearer por padrão. Ambos os headers são aceitos, então o SDK funciona sem nenhuma configuração extra.

Escopos de Chave¶

Cada API key é emitida com um ou mais escopos que controlam quais endpoints ela pode acessar.

Escopo	Endpoints Acessíveis	Caso de Uso Típico
`full_access`	Todos os endpoints	Serviços internos, ferramentas de administração
`assistant`	`POST /v1/responses`	Integrações de chat, backends de funcionalidades de IA
`user`	`/v1/memory/`, `/user-claims/`	Gerenciamento de perfil de usuário, fluxos de opt-out de memória

Princípio do menor privilégio

Solicite apenas os escopos que sua integração precisa. Uma chave com escopo assistant não pode ler nem escrever user claims, limitando o impacto caso a chave vaze.

Detalhes dos Escopos¶

full_access

Concede acesso irrestrito a todos os endpoints da API. Use apenas para serviços de backend confiáveis que precisam gerenciar tanto dados de conversação quanto dados de usuário.

assistant

Concede acesso apenas ao POST /v1/responses. Este é o escopo certo para um serviço de backend que:

Envia mensagens do usuário para um assistant
Recebe respostas com ou sem streaming
Invoca tools e lida com callbacks requires_action

user

Concede acesso aos endpoints com escopo de usuário:

GET /user-claims/:userId
GET /user-claims/:userId/:claimKey
POST /user-claims
POST /user-claims/bulk
DELETE /user-claims/:userId/:claimKey
GET /v1/memory
DELETE /v1/memory
POST /v1/memory/opt-out
DELETE /v1/memory/opt-out
DELETE /v1/memory/:itemId

Headers Opcionais¶

Além do header de autenticação, alguns headers opcionais controlam o comportamento em tempo de execução.

`x-user-id`¶

Um identificador de string para o usuário final que está fazendo a request. Quando fornecido, o assistant usa esse ID para carregar e salvar memória por usuário.

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "What did we discuss last time?" }'

Formato do user ID

O valor de x-user-id é uma string opaca do ponto de vista do Nodexa. Use qualquer identificador natural do seu sistema (UUID do banco de dados, e-mail com hash, etc.). Evite usar PII como endereços de e-mail em texto puro como IDs de usuário.

`x-user-token`¶

Um token de autenticação único do usuário final, encaminhado diretamente para servidores MCP durante chamadas de tools. Isso permite que servidores MCP verifiquem a identidade do usuário de forma independente, sem confiar no Nodexa como intermediário.

O caso de uso mais comum é encaminhar um Firebase ID token para que seu servidor MCP possa chamar verifyIdToken() diretamente:

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-token: eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Mostre meus itens salvos" }'

Como funciona o fluxo:

App mobile (Firebase ID token)
  → Seu backend (verifica o token, encaminha)
    → Nodexa (header x-user-token)
      → Chamada de tool no servidor MCP (x-user-token encaminhado)
        → Firebase Admin verifyIdToken() → uid → operações no Firestore

Seu servidor MCP recebe o token e o verifica:

const decodedToken = await getAuth().verifyIdToken(userToken);
const uid = decodedToken.uid;
// prossiga com operações no Firestore como este usuário

Quando usar x-user-token vs x-user-id

Use x-user-token quando seu servidor MCP precisar verificar independentemente a identidade do usuário (ex: tokens Firebase, Auth0, Supabase). Use x-user-id quando o Nodexa precisar apenas de um identificador de usuário para memória e rastreamento de conversas. Você pode usar ambos juntos.

Tratamento do token

O Nodexa trata o token como uma string opaca — não valida nem decodifica. O token é encaminhado aos servidores MCP exatamente como recebido. A expiração e verificação do token são responsabilidade do servidor MCP.

`x-user-tokens`¶

Um objeto JSON mapeando identificadores de provedores OAuth para access tokens. Use quando uma tool configurada no assistant precisar de credenciais OAuth de um usuário (por exemplo, acessar o Google Calendar ou o GitHub em nome do usuário).

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_abc123" \
  -H "x-user-tokens: {\"google\": \"ya29.a0...\"}" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "What meetings do I have tomorrow?" }'

Consulte API Keys — OAuth Token Passthrough para o formato completo.

Erros de Autenticação¶

Status HTTP	Erro	Significado
`401 Unauthorized`	`missing_api_key`	Nenhum header de API key foi enviado
`401 Unauthorized`	`invalid_api_key`	A chave está malformada ou não foi reconhecida
`403 Forbidden`	`insufficient_scope`	A chave não tem o escopo necessário para este endpoint

Exemplo de corpo de resposta de erro:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Consulte Erros para a referência completa de erros.