Keys guide
API Keys — create, use, and keep them safe
How nx_live_ keys work, where to put them, how to verify them, and how to rotate or revoke without breaking production.
Every metered Nexus API call needs an API key. When you create one, Nexus shows a full secret that starts with nx_live_ followed by a long hex string. That plaintext is shown once — Nexus stores only a SHA-256 hash afterward. Authenticate against /api/v1 with Authorization: Bearer nx_live_… or x-api-key: nx_live_…. Chat and image playgrounds may use a short device trial; production IDEs, SDKs, and servers must use a real key plus wallet balance. The dashboard table shows a short prefix for identification only — never paste just the prefix into Codex, Cursor, or env files.
Step-by-step
- 01
Fund the wallet first
Open Wallet and confirm you have prepaid USD balance. A valid key with $0 balance still returns 402 Payment Required on metered calls. Top up via M-Pesa, Paystack, or crypto before you wire production tools.
- 02
Open API Keys
In the developer console go to Account → API Keys (/dashboard/keys). You will see active keys (name, prefix, created date) and controls to create or revoke.
- 03
Create a named key
Click Create, give a human name (e.g. “cursor-laptop”, “prod-api”, “ci-github”), then generate. Copy the full nx_live_… secret immediately into a password manager or server secret store. Close the reveal dialog only after you have saved it — Nexus cannot show the plaintext again.
- 04
Store it as an environment variable
Prefer server-side env vars such as OPENAI_API_KEY or NEXUS_API_KEY=nx_live_…. Never commit .env files. For OpenAI-compatible SDKs, also set the base URL to https://YOUR_HOST/api/v1 (see Connect).
- 05
Authenticate on /api/v1
Send either header: Authorization: Bearer nx_live_… or x-api-key: nx_live_…. Target /api/v1/chat/completions for chat and /api/v1/images/generations for images. The model id must match Models (for example gpt-4o).
- 06
Verify before you scale
Use Connect → Verify key, or send one tiny non-streaming completion. Interpret status: 401 = bad/revoked/truncated secret or wrong host; 402 = empty wallet; 2xx or a healthy stream = ready. Then confirm a row appears under Requests.
- 07
Rotate without downtime
Create a new key → update every client/CI secret → confirm traffic works → revoke the old key. Revocation is immediate: anything still holding the old secret will get 401 on the next request.
- 08
Revoke compromised keys
If a laptop is stolen or a secret leaked in git/chat, revoke that key on API Keys right away, rotate replacements, and skim Requests for unexpected usage.
Tips
One key per environment
Separate keys for laptop, CI, staging, and production. You can revoke a leaked laptop key without killing prod.
Server-side only
Never ship nx_live_ secrets in browser JS, mobile apps, public repos, or client-side Next.js bundles. Keep them on the server or in a secrets manager.
Name keys for humans
Names like “cursor-home” beat “key-3” when you audit Requests or revoke after a device loss.
Prefix ≠ secret
The table prefix is only a label. Clients must use the full secret copied at creation time.
Match host and protocol
After you deploy, recreate Connect config on your real domain so tools do not keep calling localhost or http when you need https.
Playground keys are optional
Chat/Images can run on trial or wallet rules. Purchased keys appear in the playground dropdown when you have created them — useful for testing the exact secret your IDE will use.
Frequently asked questions
I lost the full key. Can Nexus show it again?+
No. Only a hash is stored. Create a new key, update every client, then revoke the old one if it still exists.
Bearer or x-api-key — which should I use?+
Both work on Nexus. OpenAI SDKs usually send Authorization: Bearer. Some proxies and no-code tools prefer x-api-key. Pick one style per integration and stay consistent.
Why do I get 401 right after creating a key?+
Most often: truncated copy, trailing space/newline, using only the dashboard prefix, or the client still pointing at api.openai.com instead of your Nexus /api/v1 base URL.
Why do I get 402 with a valid key?+
402 means the account wallet cannot cover the call. Top up under Wallet/Billing. Keys do not carry separate balances.
Does each key have its own balance?+
No. Every key under your user meters against the same prepaid wallet.
Can I use playground without creating a key?+
Chat/Images may allow a short device trial without exposing remaining counts. For Codex, Cursor, CI, and any /api/v1 client you need an nx_live_ key and funds.
How many keys can I create?+
Create what you need for isolation (dev/stage/prod). Revoke unused keys so the list stays auditable. If you hit a platform limit, revoke old ones or contact Support.
Will revoking break in-flight streams?+
New requests fail with 401 immediately. Finish rotation on clients before you revoke the old secret in production.
Where do I see which key spent money?+
Open Requests for metered calls and correlate time/model/cost. Use clear key names so support and audits are easier.
Common mistakes
- Pasting only the visible prefix into Codex, Cursor, or .env
- Committing .env or CI logs that contain nx_live_ secrets
- Leaving revoked keys in GitHub/GitLab secrets after rotation
- Sharing one team-wide key with no owner and no rotation plan
- Debugging “broken models” while every Requests row is 401/402
- Running Connect on localhost after production DNS cutover
Related
Opens in a new tab.