API Keys¶

Esta página cobre os detalhes técnicos das API keys do Nodexa: formato, semântica de escopos e como passar tokens OAuth por provedor nas requests.

Formato da Chave¶

As API keys do Nodexa seguem esta estrutura:

nxk_<base64url-encoded-encrypted-payload>

O prefixo nxk_ identifica a chave como uma chave Nodexa
O payload é um blob criptografado contendo o escopo, a organização e os metadados da chave
As chaves são geradas no servidor e emitidas por um administrador da plataforma
As chaves não expiram automaticamente — devem ser explicitamente revogadas

Exemplo (placeholder — não é uma chave real)¶

nxk_eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0.abc123xyz.def456uvw.ghi789rst.jkl012mno

As chaves são opacas para os clientes

Não tente decodificar o payload de uma API key. O formato interno pode mudar sem aviso. A única fonte confiável para ver o escopo e os metadados de uma chave é o painel administrativo da plataforma.

Referência de Escopos¶

Os escopos controlam quais endpoints da API uma chave pode acessar.

`full_access`¶

Permissão	Valor
Chamar `POST /v1/responses`	Sim
Ler/escrever user claims	Sim
Ler/escrever/excluir memória	Sim
Acessar todos os futuros endpoints	Sim

Destinado a serviços internos confiáveis, como ferramentas de administração ou camadas de orquestração de backend.

`assistant`¶

Permissão	Valor
Chamar `POST /v1/responses`	Sim
Ler/escrever user claims	Não
Ler/escrever/excluir memória	Não

Destinado a serviços de backend que integram funcionalidade de chat em uma aplicação.

`user`¶

Permissão	Valor
Chamar `POST /v1/responses`	Não
Ler/escrever user claims	Sim
Ler/escrever/excluir memória	Sim

Destinado a serviços de backend que gerenciam dados de perfil de usuário e preferências de memória separadamente do fluxo de chat.

Passando sua API Key¶

Confira Autenticação para as opções de header. Em resumo:

x-api-key: nxk_your_key_here

ou de forma equivalente:

Authorization: Bearer nxk_your_key_here

OAuth Token Passthrough¶

Alguns assistants têm tools que atuam em nome de um usuário específico — por exemplo, acessar o Google Calendar, ler repositórios no GitHub ou postar no Slack. Para essas tools funcionarem, você precisa encaminhar o access token OAuth do usuário junto com a request da API.

O Header `x-user-tokens`¶

Passe um objeto JSON onde as chaves são identificadores de provedor e os valores são os access tokens OAuth correspondentes:

x-user-tokens: {"<provider_id>": "<access_token>", ...}

Exemplo com múltiplos provedores:

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.a0AfH...", "github": "gho_abc123..."}' \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ASSISTANT_ID",
    "input": "Summarize my open GitHub PRs and my meetings for tomorrow."
  }'

Como a Plataforma Usa Esses Tokens¶

A plataforma Nodexa recebe a request com x-user-tokens
Quando um Agente Especialista invoca uma tool que precisa de credenciais de um provedor específico, a plataforma busca o token correspondente no header
O token é usado para fazer a chamada à API downstream em nome do usuário
Os tokens nunca são armazenados — são usados apenas durante a duração da request

IDs de Provedor¶

Os IDs de provedor correspondem aos identificadores configurados nos plugins da sua instância Nodexa. Exemplos comuns:

Provedor	ID Típico
Google (Calendar, Drive, Gmail)	`google`
GitHub	`github`
Slack	`slack`
Microsoft (Outlook, Teams)	`microsoft`

Fale com seu administrador Nodexa para saber os IDs de provedor exatos configurados na sua instância.

Evento OAuth Required¶

Se uma tool precisa de credenciais OAuth mas nenhuma foi fornecida (ou o token expirou), a plataforma emite um evento oauth_required no stream SSE:

{
  "type": "response.output_item.added",
  "item": {
    "type": "oauth_required",
    "plugin_id": "plugin_abc123",
    "plugin_name": "Google Calendar",
    "provider_id": "google",
    "required_scopes": ["https://www.googleapis.com/auth/calendar.readonly"],
    "auth_url": "https://your-admin.example.com/oauth/google/authorize?state=..."
  }
}

Sua aplicação deve:

Detectar o item oauth_required no stream
Redirecionar o usuário para auth_url para completar o fluxo OAuth
Armazenar o access token resultante
Reenviar a request original com o token em x-user-tokens

Confira Eventos SSE — oauth_required para a documentação completa dos campos.

Boas Práticas de Segurança para Chaves¶

Nunca exponha chaves no código client-side

JavaScript no navegador, apps mobile e outros ambientes client-side são inerentemente inseguros. Sempre roteie as chamadas de API por um serviço de backend que você controla.

Armazene chaves em variáveis de ambiente ou em um gerenciador de segredos:

# .env (nunca faça commit deste arquivo)
NODEXA_API_KEY=nxk_your_key_here

// Acesso em Node.js
const apiKey = process.env.NODEXA_API_KEY;

Rotacione as chaves periodicamente: Trabalhe com seu administrador Nodexa para emitir novas chaves regularmente, especialmente após qualquer suspeita de vazamento.

Use o escopo mais restrito possível: Se o seu serviço só envia mensagens de chat, solicite uma chave com escopo assistant. Isso limita o impacto caso a chave vaze.

Audite o uso das chaves: Seu administrador Nodexa pode revisar os logs de uso das API keys para detectar padrões anormais.