Assets vía API

Los assets son valores reutilizables que tus robots necesitan en tiempo de ejecución: rutas, direcciones de correo, claves de API de terceros, usuarios y contraseñas. NORA los almacena cifrados por tenant y permite que un robot los lea bajo demanda mediante una API key, sin tener que incrustar secretos en el código del proceso.

Esta página documenta el único endpoint público de assets: la lectura por nombre. Para crear y administrar assets desde el panel, consulta la guía de assets y credenciales.

Tipos de asset

Cada asset tiene un type que determina cómo se usa y si su valor puede revelarse desde el orquestador:

Tipo	Descripción	Campos devueltos
`text`	Valor no sensible (rutas, URLs, correos, identificadores). Puede revelarse también desde la UI.	`value`
`credential`	Par usuario/contraseña. Requiere `username` al crearse.	`value`, `username`
`secret`	Valor sensible de un solo campo (token, clave de API de un tercero).	`value`
`vault`	Referencia a un secreto en un proveedor externo (vault). Se resuelve en el momento de la lectura.	`value` (y `username` si el proveedor lo expone)

Además, cada asset pertenece a un entorno (environment): dev, staging o production (por defecto production). El nombre de un asset es único por tenant y entorno, de modo que puedes tener el mismo db_password con valores distintos en dev y en production.

Leer un asset por nombre

GET /api/v1/assets/by-name/{name}?environment=production

URL base de producción: https://nora.valisoftconsulting.com. La autenticación es por cabecera X-API-Key (consulta autenticación).

Parámetros

Parámetro	Ubicación	Requerido	Descripción
`name`	ruta	sí	Nombre exacto del asset.
`environment`	query	no	Entorno del asset. Por defecto `production`. Valores: `dev`, `staging`, `production`.

Requisitos de la API key

La API key debe tener el scope assets:read. La verificación es fail-closed: una key sin ese scope explícito recibe 403.
Si la key declara una lista de entornos permitidos, el environment solicitado debe estar en ella. Por ejemplo, una key restringida a ["dev"] no puede leer assets de production —así, una key filtrada de CI/CD no permite exfiltrar secretos de producción.
Límite de uso: 30 peticiones por minuto por IP.
Cada lectura exitosa queda registrada en el log de auditoría del tenant (acción access sobre el recurso asset), incluyendo el nombre de la key y el entorno consultado.

Respuesta

La respuesta va envuelta en el sobre estándar SuccessResponse ({"success": true, "data": ...}). El objeto data es un AgentAssetResponse:

{
  "success": true,
  "data": {
    "name": "sap_login",
    "type": "credential",
    "environment": "production",
    "value": "S3cr3t-P4ss",
    "username": "robot_finanzas"
  }
}

El campo username solo aparece cuando el asset lo tiene (típicamente los de tipo credential). Para text, secret y la mayoría de vault, la respuesta incluye únicamente value además de name, type y environment.

Errores

Código	Causa
`403`	La API key no tiene el scope `assets:read`, o el `environment` solicitado no está en la lista permitida de la key.
`404`	No existe un asset con ese `name` en el `environment` indicado.
`422`	Parámetros inválidos.
`429`	Se superó el límite de 30 peticiones por minuto.

Consulta el formato completo del sobre de error en errores y límites.

Ejemplos

curl

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

Python

import httpx

API = "https://nora-api.valisoftconsulting.com/api/v1"
HEADERS = {"X-API-Key": "nora_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

resp = httpx.get(
    f"{API}/assets/by-name/sap_login",
    params={"environment": "production"},
    headers=HEADERS,
)
resp.raise_for_status()

asset = resp.json()["data"]
usuario = asset.get("username")
password = asset["value"]
# usar las credenciales en el robot...

Flujo de consumo

sequenceDiagram
    participant Bot as Robot (agente)
    participant API as NORA API
    participant DB as Almacén cifrado

    Bot->>API: GET /assets/by-name/{name}?environment=...<br/>X-API-Key: nora_ak_...
    API->>API: Valida key + scope assets:read + entorno
    API->>DB: Busca asset (tenant, name, environment)
    DB-->>API: Asset cifrado
    API->>API: Descifra value/username + registra auditoría
    API-->>Bot: { "data": { value, username, ... } }