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, flujos avanzados

Los tres llevan el contexto de tenant + permisos por alcance (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 los datos de membership cambiaron 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 con alcance completo.

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 consultando 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 delimitadas por tenant y por rol. Generálas vía el portal admin de Tracium o la API admin. Rotálas si se comprometen.

Las API keys son secretos bearer

Nunca las subas al repositorio. Usá archivos .env, gestores de secretos (AWS Secrets Manager, GCP Secret Manager, Vault). Tratálas como contraseñas 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 contraseña.

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 flujo 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 mapa de procesos.

El JWT lleva el process scope. Las llamadas a eventos fuera del alcance otorgado son rechazadas 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 flujo de prepared-transaction
• Sandbox: conseguir credenciales sandbox para evaluación