Autenticación

Darwin soporta tres métodos de autenticación en la API pública. Elegí por audiencia:

Método	Audiencia	Dónde se usa
JWT bearer token	end users (humanos)	operadores Captia, portal Tracium, dashboards
API key	integraciones server-to-server	consumers de webhooks, batch jobs, conectores ERP
Sign-In with Ethereum (SIWE)	identidad basada en wallet	operadores Web3-native, flows avanzados

Los tres llevan el contexto de tenant + permisos por scope (ver Tenants e identidad).

JWT bearer (lo más común)

Paso 1: Login

POST /api/v2/auth/login — el tenantId es opcional:

curl -X POST "$BASE_URL/api/v2/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@example.com",
    "password": "tu-password",
    "tenantId": "tnt_a1b2c3"
  }'

Respuesta:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "partial": false
}

Campos de la respuesta:

• accessToken — JWT v2 firmado.
• refreshToken — para renovar el access token.
• partial: true — aparece cuando el access token está sin tenant (login sin tenantId y el usuario tiene múltiples memberships). Tenés que llamar /select-tenant antes de usarlo.
• stale: true — aparece si la data de membership cambió y se recomienda re-autenticar.

Paso 2: Seleccionar tenant (si el token vino partial)

Si el token vino partial: true, promovelo:

curl -X POST "$BASE_URL/api/v2/auth/select-tenant" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "tnt_a1b2c3" }'

La respuesta incluye un nuevo accessToken full-scope.

Para listar las memberships del usuario y elegir un tenant:

curl "$BASE_URL/api/v2/auth/memberships" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Devuelve un array con slug, name, onChainTenantId, tenantContractAddress por cada tenant del usuario.

Cambiar de tenant durante una sesión

Para usuarios con múltiples memberships, cambiar el contexto activo:

curl -X POST "$BASE_URL/api/v2/auth/switch-tenant" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "tnt_otra" }'

Paso 3: Llamar API con bearer

curl "$BASE_URL/api/v1/events" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refresh

La vida del JWT es corta (1h típico). Usá el refreshToken del login para emitir un nuevo access token.

API key (server-to-server)

Para integraciones backend — tu ERP polleando Tracium, un job de analytics, un consumer de webhooks.

curl "$BASE_URL/api/v1/events" \
  -H "X-API-Key: $API_KEY"

Las API keys están scopeadas por tenant y por rol. Generálas vía el portal admin de Tracium (o la API admin write-ops de Q3-2026). Rotálas si se comprometen.

Las API keys son secrets bearer

Nunca las committees. Usá archivos .env, secrets managers (AWS Secrets Manager, GCP Secret Manager, Vault). Tratálas como passwords de DB.

Sign-In with Ethereum (SIWE)

Para operadores wallet-native — operadores que ya tienen una wallet Ethereum (MetaMask, WalletConnect, hardware wallet) y prefieren firmar con su wallet en vez de password.

Paso 1: Conseguir un nonce

curl "$BASE_URL/api/v2/auth/siwe/nonce"

Respuesta: un nonce string generado por el server.

Paso 2: Firmar en la wallet

En tu front-end (o integración de wallet), construí el mensaje SIWE según EIP-4361, incluí el nonce, y hacé que el usuario firme.

Paso 3: Enviar mensaje firmado

curl -X POST "$BASE_URL/api/v2/auth/siwe" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "<el mensaje SIWE>",
    "signature": "<hex firmado por la wallet>"
  }'

Respuesta: accessToken igual al flow JWT bearer.

Process-scope grants

Más allá del acceso por rol, Darwin soporta least-privilege grants por proceso — un operador puede estar autorizado solo para eventos de wool_shearing, sin desbloquear todo el process map. Esto shipeó como parte de la initiative 2026-05-process-scope-grants.

El JWT lleva el process scope; calls a eventos fuera del scope otorgado son rechazados en la capa de API.

Identificarte

curl "$BASE_URL/api/v2/auth/me" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Devuelve el JWT v2 payload completo: sub, email, wallet, did, tid (slug del tenant), tenantUuid, roles[], roleScopes (process-scope grants en efecto), profileComplete, isPlatformAdmin, memberships[], username, orgs[], orgId.

Adónde ir después

• Quickstart — enviar un evento con el flow de prepared-transaction
• Sandbox — conseguir credenciales sandbox para evaluación