Assets y credenciales

Un asset es un valor reutilizable que vive en NORA y que tus robots consumen en tiempo de ejecución: una ruta de carpeta, una dirección de correo, un usuario y contraseña, una API key, etc. En lugar de incrustar estos datos en el código del proceso, los defines una vez en NORA y el robot los pide por nombre cuando los necesita.

Los assets están cifrados en reposo (cifrado autenticado con una clave maestra y datos asociados —AAD— que vinculan cada ciphertext a su campo) y están aislados por organización (tenant): un robot solo puede leer los assets de su propia organización.

Tipos de asset

Un asset tiene un campo type que determina cómo se almacena y si su valor puede revelarse desde la interfaz.

Tipo	Descripción	¿Legible desde el Robots Center?
text	Valor de configuración no sensible (ruta, correo, URL, parámetro).	Sí, un administrador puede revelarlo.
credential	Par usuario + contraseña/secreto. El campo username es obligatorio.	No (solo escritura).
secret	Valor sensible único (API key, token, contraseña).	No (solo escritura).
vault	Referencia a un secreto guardado en un vault externo; el valor se resuelve en cada lectura.	No (se resuelve en tiempo de ejecución).
integer · number · bool	Valor de configuración tipado: el robot recibe un int, float o bool ya convertido (no un string).	Sí (no son secretos).

Valores tipados en el robot

Para un asset integer/number/bool, sdk.get_asset("...")["value"] devuelve el valor ya tipado (3, 19.9, True), no "3". Útil para parámetros de configuración (umbrales, flags) que el robot usa directamente sin castear.

Secretos de solo escritura

Una vez guardado, el valor de un asset secret o credential no puede volver a leerse desde la interfaz del Robots Center. El endpoint GET /api/v1/assets/{asset_id}/value devuelve 403 Forbidden para estos tipos y registra el intento en el log de auditoría. Solo los assets text pueden revelarse en la UI. Si pierdes el valor, actualízalo; no podrás recuperarlo.

Identidad de un asset

Cada asset se identifica por la combinación nombre + entorno dentro de la organización (restricción única). El campo environment puede ser dev, staging o production (por defecto production). Esto te permite tener, por ejemplo, un asset api-erp distinto en staging y en production sin colisión.

Campos disponibles al crear un asset:

Campo	Requerido	Notas
name	Sí	Nombre lógico, único por entorno.
type	Sí	text, credential, secret o vault.
value	Sí	Valor a cifrar (o, para vault, la configuración del proveedor).
username	Solo credential	Usuario asociado a la credencial.
description	No	Texto libre.
expires_at	No	Marca de caducidad (informativa).
environment	No	dev | staging | production (por defecto production).

Assets de tipo credencial

Un asset credential guarda dos partes cifradas por separado: el username y el value (la contraseña o secreto). Ambos campos son obligatorios al crear el asset; si omites username, la API responde con error de validación.

curl -X POST https://nora-api.valisoftconsulting.com/api/v1/assets \
  -H "Authorization: Bearer <token_de_sesion>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp-login",
    "type": "credential",
    "username": "robot_facturacion",
    "value": "S3cret0-ERP",
    "environment": "production"
  }'

La respuesta va envuelta en {"data": ...} y nunca incluye el valor ni el usuario descifrados, solo los metadatos del asset:

{
  "data": {
    "id": "a1b2c3d4-0000-0000-0000-000000000000",
    "name": "erp-login",
    "type": "credential",
    "environment": "production",
    "description": null,
    "expires_at": null,
    "created_at": "2026-06-19T10:00:00Z",
    "updated_at": "2026-06-19T10:00:00Z"
  }
}

Crear, actualizar y eliminar assets requiere rol admin; listarlos y ver sus metadatos también lo permite el rol operator.

Integración con vaults externos

Un asset de tipo vault no guarda el secreto en NORA: guarda la configuración de conexión a un vault externo y resuelve el valor en cada lectura. Proveedores soportados:

• azure_keyvault — Azure Key Vault (REST API + credenciales de cliente OAuth2).
• aws_secrets_manager — AWS Secrets Manager (vía boto3).
• hashicorp_vault — HashiCorp Vault (API HTTP, KV v1 y v2).

La configuración del proveedor se guarda como JSON en el campo value e incluye, como mínimo, las claves provider y secret_name, más los parámetros propios del proveedor:

Proveedor	Campos requeridos	Opcionales
azure_keyvault	vault_url, azure_tenant_id, azure_client_id, azure_client_secret	—
aws_secrets_manager	aws_region	aws_access_key_id, aws_secret_access_key
hashicorp_vault	vault_url, vault_token	mount_path (def. secret), kv_version (def. 2)

Cuando el secreto del vault es un JSON con username/password (AWS y HashiCorp), NORA devuelve value (la contraseña) y username.

Protección SSRF

La vault_url la controla el usuario, por lo que NORA la valida y rechaza destinos privados o reservados (por ejemplo, IPs internas o el endpoint de metadatos de la nube 169.254.169.254).

Cómo los usa un robot (dentro de un job gestionado)

Los robots no usan tu sesión ni una cabecera X-API-Key. Cuando lanzas un job, el agente inyecta un token de ejecución por job (nora-exec) acotado a esa ejecución, y el SDK lo usa de forma transparente. En el código del proceso pides el asset por nombre:

from nora_agent import sdk

cred = sdk.get_asset("erp-login")
cred["username"], cred["value"]

Por debajo, get_asset hace GET /api/v1/agent/assets/{name}?environment=... con la cabecera Authorization: Bearer <token de ejecución>. Si el proceso declara un manifiesto de assets, el agente los precarga en la variable NORA_ASSETS antes de arrancar, de modo que get_asset los resuelve sin tráfico de red.

No metas claves nora_ak_ en el robot

Nunca incrustes una X-API-Key (nora_ak_...) en el código del proceso. Al empaquetar con nora package la operación aborta si detecta secretos en el código. Los valores se leen siempre con sdk.get_asset, que usa el token de ejecución del job.

Lectura desde un sistema externo (API pública, X-API-Key)

Un sistema fuera de NORA (otra aplicación, un script de integración) puede leer assets a través de la API pública con una cabecera X-API-Key (clave nora_ak_...) que debe tener el scope assets:read. El endpoint busca por nombre y entorno y devuelve el valor descifrado (o resuelto desde el vault):

curl "https://nora-api.valisoftconsulting.com/api/v1/assets/by-name/erp-login?environment=production" \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxx"

{
  "data": {
    "name": "erp-login",
    "type": "credential",
    "environment": "production",
    "value": "S3cret0-ERP",
    "username": "robot_facturacion"
  }
}

Detalles de comportamiento:

• Requiere scope assets:read (o una key sin restricción de scopes).
• Si la API key declara una lista blanca de entornos, el environment pedido debe estar en ella.
• El endpoint está limitado a 30 peticiones por minuto por IP.
• Cada lectura exitosa queda registrada en el log de auditoría de la organización.

sequenceDiagram
    participant Bot as Robot (agente)
    participant Ext as Sistema externo
    participant API as API NORA
    participant Vault as Vault externo
    Bot->>API: GET /api/v1/agent/assets/{name}<br/>Authorization: Bearer (token nora-exec)
    Ext->>API: GET /api/v1/assets/by-name/{name}<br/>X-API-Key (assets:read)
    alt Asset tipo vault
        API->>Vault: Resuelve secreto (Azure/AWS/HashiCorp)
        Vault-->>API: value (+ username)
    else text / credential / secret
        API->>API: Descifra value (+ username)
    end
    API-->>Bot: { "data": { value, username, ... } }
    API-->>Ext: { "data": { value, username, ... } }

Consejo

Pide cada asset por nombre justo cuando lo necesites y no lo persistas en disco ni en logs del proceso. Para credenciales y secretos, esta es la única forma de obtener el valor: la interfaz nunca lo revela.

Referencias de API

• Assets (API pública) — endpoint GET /assets/by-name/{name} y detalles de scopes.
• Autenticación — cómo crear y usar API keys nora_ak_....
• Jobs — cómo un robot ejecuta procesos que consumen assets.

Consulta Assets (API pública) y la referencia de la API para los endpoints relacionados.