Autenticação

API key por tenant

Toda requisição ao broker autentica com uma API key de tenant, no header Authorization: Bearer <apiKey>. O SDK cuida disso: você passa a key ao construtor e ela viaja só no header — nunca no corpo, nunca na URL, nunca em log. apiKey é o único argumento obrigatório: baseUrl é opcional (default https://api.grwthy.com; sobrescreva só para self-host) e apiVersion também é opcional (default v1).

import { WaBroker } from '@wabroker/sdk'

const wa = new WaBroker({
  apiKey: process.env.WABROKER_API_KEY!,
  // baseUrl e apiVersion são opcionais — só informe para sobrescrever o
  // default (https://api.grwthy.com, v1), ex. num self-host.
  baseUrl: process.env.WABROKER_BASE_URL, // opcional
})

Em C# (ASP.NET)

Em vez de instanciar o cliente manualmente, registre-o no container de DI uma vez, na inicialização, e injete WabrokerClient por construtor onde precisar dele. Assim como no construtor direto, só ApiKey é obrigatório — BaseUrl e ApiVersion ficam nos defaults se você não os definir:

// não há equivalente — o SDK TypeScript não integra a um container de DI

Escopo

A key identifica um único tenant, e o broker escopa tudo a ele automaticamente. Você nunca informa um tenantId nas chamadas — ele vem da key. Um número, mensagem ou template de outro tenant responde como 404 (inexistente), nunca 403: o isolamento não confirma sequer a existência de recursos alheios.

Gerenciar keys

O namespace apiKeys cria, lista e revoga keys do tenant.

// Criar — a key em claro aparece UMA vez, aqui. Capture-a agora.
const created = await wa.apiKeys.create({ label: 'backend-produção' })
console.log(created.apiKey) // sk_tn_… — nunca mais reexibida
console.log(created.last4)  // depois, só isto identifica a key

// Listar — sempre mascaradas (last4 + label + se está revogada)
const keys = await wa.apiKeys.list()

// Revogar por id
await wa.apiKeys.revoke(created.id)

• create({ label }) devolve CreatedApiKey com apiKey em claro — a única vez que ela é exibida.
• list() devolve ApiKeyInfo[] mascaradas (last4, label, revoked) — nunca a key nem o hash.
• revoke(id) resolve void.

Rotação sem downtime

Para trocar uma key: crie a nova, atualize o segredo no seu backend e só então revogue a antiga. O broker recusa revogar a última key ativa do tenant (evita auto-lockout) — respondendo api_key_last_active (HTTP 409). Sempre exista outra key ativa antes de revogar.

import { BrokerApiError } from '@wabroker/sdk'

const next = await wa.apiKeys.create({ label: 'rotação-2026-07' })
await deployNewKeyToBackend(next.apiKey) // atualize o env e reinicie o processo

try {
  await wa.apiKeys.revoke(oldKeyId)
} catch (err) {
  if (err instanceof BrokerApiError && err.code === 'api_key_last_active') {
    // Você tentou revogar a única key ativa — crie outra antes.
  }
  throw err
}