API keys

API keys are workspace-scoped credentials for the public /v1 API. They are managed from the dashboard under Settings → API keys. There is one key system across the platform — the same key works for payments and verification; there are no per-product keys.

Create a key

1. Open Settings → API keys in the dashboard.
2. Choose Create key.
3. Give it a name you will recognise in an incident — Production server, Staging worker, or the name of the service that holds it.
4. Choose an environment: live (default) or test.
5. Select scopes. Leaving the selection empty grants all four scopes.

The response is the only time the full key is available:

nvs_live_sk_1a2b3c4d5e6f_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0

Copy it into your secret manager immediately. Nuansis stores sha256(secret) and the non-secret prefix; it cannot re-display or recover the secret. If it is lost, revoke the key and mint a new one.

Environment label

live and test are recorded on the key and appear in key metadata. The current API has no separate sandbox host or isolated sandbox dataset — both labels call the same /v1 endpoints on the same workspace. See Quickstart.

What the dashboard shows

The key list never includes the secret. Each row contains:

Field	Meaning
id	Numeric key id, used for revocation
name	Label you gave the key
prefix	The 12-character non-secret prefix, for identifying a key in logs
environment	live or test
scopes	Granted scopes
active	false once revoked
last_used_at	Last authenticated request, updated at most once per minute
revoked_at	When the key was revoked, or null
created_at	Creation timestamp

Revoke a key

Use the revoke action next to the key in Settings → API keys. Revocation takes effect immediately: the authentication query excludes revoked rows, so the next request with that key returns 401 unauthorized / invalid_api_key.

Revocation is permanent. To restore access, create a new key.

Rotate without downtime

1. Create a second key with the same scopes and environment.
2. Add it to your deployment’s secret store and roll it out.
3. Watch last_used_at on the old key until it stops moving.
4. Revoke the old key.

Because rate limits are tracked per key id, the new key starts with a fresh budget during the overlap — useful when rotating a busy integration.

Under the hood

The dashboard calls three JWT-authenticated endpoints. They are documented here for completeness; they are not part of the API-key surface and cannot be called with a nvs_… key.

Method	Path	Purpose
GET	/api-keys	List keys for the workspace
POST	/api-keys	Mint a key — returns the plaintext key once
DELETE	/api-keys/:id	Revoke a key

POST /api-keys accepts:

{
  "name": "Production server",
  "scopes": ["collections:write", "payouts:write", "read"],
  "environment": "live"
}

All three fields are optional. Omitting scopes (or sending an empty array) grants every scope; omitting environment mints a live key.

Handling keys safely

• Keep keys server-side. Never ship one in a browser bundle, mobile binary, or public repository.
• Use a separate key per service and per environment so a leak has a small blast radius.
• Prefer the narrowest scope set that works. A read-only reporting job should hold only read.
• Log the prefix, never the full key. The prefix is designed to be safe to display.
• Subscribe to webhooks rather than polling, and keep key usage to what you need.