API keys

API keys authenticate your server to the NU Signal Partners API. After a partner application is approved, you can issue, rotate, and revoke keys directly through API endpoints without a web console.

Get the first key (bootstrap)

After approval, call POST /partner-applications/claim with the application status credentials to receive a one-time approval token (prefix nsp_appr_, valid for 72 hours). Because no API key exists yet, only this endpoint is public and gated by that token. Exchange it for the first Sandbox key:

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"
  }
}

The approval claim and bootstrap token are each consumed on success. A second call returns 401 invalid_approval_token. If the token is lost, ask NU to reissue it. The bootstrap key includes administrative scopes so it can create narrower integration keys. Keep at least one server-side management key with api_keys:write; Production runtime keys generally should not have key-management scopes.

API key endpoints

Method and path	Required permission	Purpose
`POST /v1/api-keys/bootstrap`	Approval token	Public — issue the first Sandbox key from an approval token.
`GET /v1/api-keys`	`api_keys:read` or `api_keys:write`	List keys; secrets are never returned.
`POST /v1/api-keys`	`api_keys:write`	Create another key. Production requires an ACTIVE Production deal with `production_api_enabled: true`; otherwise it returns `license_not_active`.
`PATCH /v1/api-keys/{id}`	`api_keys:write`	Update scopes, allowed_origins, or allowed_ips.
`POST /v1/api-keys/{id}/rotate`	`api_keys:write`	Issue a replacement and revoke the old key.
`DELETE /v1/api-keys/{id}`	`api_keys:write`	Revoke a key.

Sandbox and Production keys

	Sandbox	Production
Prefix	`nsp_test_`	`nsp_live_`
Base URL	`https://signal-partners.newunivers.ai/v1`	`https://signal-partners.newunivers.ai/v1`
Data	Isolated dummy catalog (isSandbox)	Real catalog, deals, and revenue
Playback	No license required	ACTIVE license deal required
Settlements	No access to real financial statements	Read and dispute settlements

Environments are isolated by key prefix, catalog visibility, sessions, logs, and data. nsp_test_ selects Sandbox and nsp_live_ selects Production. Every request runs in the environment encoded in its key.

Secrets are shown once

The full secret is returned exactly once when the key is created. NU stores only a hash and cannot show it again. Copy it immediately to a secrets manager. If lost, revoke it and create a new key.

Status

Status	Meaning
`ACTIVE`	Available for use.
`REVOKED`	Manually disabled. Calls return `401 api_key_revoked`.
`EXPIRED`	Expired. Calls return `401 invalid_api_key`.

Rotation

POST /v1/api-keys/{id}/rotate issues a replacement with the same environment, scopes, and restrictions, then revokes the old key in one call. For zero-downtime rotation, overlap the keys instead:

Create a new key with the same scopes.
Deploy it to your servers.
Verify traffic has moved to the new key, correlating with X-NU-Request-Id.
Revoke the old key.

Rotate regularly and immediately on suspected exposure. Revocation marks the key REVOKED and rejects later calls, but does not cancel existing playback sessions or tokens; they expire by their own TTL.

Revocation

Revocation is immediate and irreversible. Every later call with that key returns 401 api_key_revoked.

Restrict where a key can be used

Control	Effect
`allowed_origins`	Playback tokens are issued only for origin values in this list.
`allowed_ips`	When configured, requests must originate from these IPs or CIDRs.
`scopes`	Limits which endpoints the key can call (Authentication).

Configure allowed_origins and allowed_ips before launch; they are part of the Production checklist. A playback origin outside allowed_origins is rejected when a token is issued.