Claves de API

Las claves autentican su servidor ante la API. Tras aprobarse la solicitud, puede emitir, rotar y revocar claves directamente mediante endpoints, sin consola web.

Obtener la primera clave (bootstrap)

Tras aprobarse, llame a POST /partner-applications/claim con las credenciales de estado para recibir un token de aprobación de un uso (prefijo nsp_appr_, válido 72 horas). Como aún no hay clave, solo este endpoint es público y está protegido por el token. Cámbielo por la primera clave de Sandbox:

curl -X POST https://signal-partners.newunivers.ai/v1/api-keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{ "approval_token": "nsp_appr_..." }'

{
  "data": {
    "api_key_id": "ak_...",
    "key_prefix": "nsp_test_4f2a1b3c",
    "environment": "sandbox",
    "scopes": ["catalog:read", "license:read", "..."],
    "status": "active",
    "secret": "nsp_test_xxxxxxxx"
  }
}

La reclamación y el token bootstrap se consumen al usarse. Una segunda llamada devuelve 401 invalid_approval_token. Si lo pierde, solicite reemisión. La clave bootstrap incluye ámbitos administrativos para crear claves más estrechas. Mantenga al menos una clave de servidor con api_keys:write; las claves runtime de Production no suelen tener gestión.

Endpoints de claves

Método y ruta	Permiso necesario	Finalidad
`POST /v1/api-keys/bootstrap`	Token de aprobación	Público: emite la primera clave de Sandbox a partir del token.
`GET /v1/api-keys`	`api_keys:read` o `api_keys:write`	Lista claves; nunca devuelve secretos.
`POST /v1/api-keys`	`api_keys:write`	Crea otra clave. Production exige un deal ACTIVE con `production_api_enabled: true`; de lo contrario devuelve `license_not_active`.
`PATCH /v1/api-keys/{id}`	`api_keys:write`	Actualiza scopes, allowed_origins o allowed_ips.
`POST /v1/api-keys/{id}/rotate`	`api_keys:write`	Emite una sustituta y revoca la anterior.
`DELETE /v1/api-keys/{id}`	`api_keys:write`	Revoca una clave.

Claves de Sandbox y Production

	Sandbox	Production
Prefijo	`nsp_test_`	`nsp_live_`
URL base	`https://signal-partners.newunivers.ai/v1`	`https://signal-partners.newunivers.ai/v1`
Datos	Catálogo de prueba aislado (isSandbox)	Catálogo, deals e ingresos reales
Reproducción	Sin licencia	Requiere deal ACTIVE
Liquidaciones	Sin acceso a estados financieros reales	Consulta e impugnación

Los entornos se aíslan por prefijo, visibilidad, sesiones, registros y datos. nsp_test_ elige Sandbox y nsp_live_, Production. Cada solicitud se ejecuta en el entorno de su clave.

Los secretos se muestran una vez

El secreto completo se devuelve una sola vez al crear la clave. NU guarda solo un hash y no puede mostrarlo de nuevo. Cópielo al gestor; si se pierde, revoque y cree otra.

Estado

Estado	Significado
`ACTIVE`	Disponible.
`REVOKED`	Desactivada manualmente. Las llamadas devuelven `401 api_key_revoked`.
`EXPIRED`	Caducada. Las llamadas devuelven `401 invalid_api_key`.

Rotación

POST /v1/api-keys/{id}/rotate emite una sustituta con el mismo entorno, ámbitos y restricciones y revoca la anterior. Para rotación sin interrupción, solápelas:

Cree una nueva con los mismos ámbitos.
Despliéguela en sus servidores.
Verifique que el tráfico usa la nueva correlacionando X-NU-Request-Id.
Revoque la anterior.

Rote regularmente y de inmediato ante exposición. La revocación marca REVOKED y rechaza llamadas futuras, pero no cancela sesiones ni tokens existentes; caducan por su TTL.

Revocación

La revocación es inmediata e irreversible. Toda llamada posterior con esa clave devuelve 401 api_key_revoked.

Restrinja dónde se usa una clave

Control	Efecto
`allowed_origins`	Los tokens se emiten solo para valores origin de esta lista.
`allowed_ips`	Si se configura, las solicitudes deben proceder de estas IP o CIDR.
`scopes`	Limita qué endpoints puede llamar la clave (Autenticación).

Configure allowed_origins y allowed_ips antes del lanzamiento; forman parte de la Lista de Production. Un origin fuera de allowed_origins se rechaza al emitir el token.