Start here
Authentication
Bearer API keys: format, live and test environments, rotation, revocation, expiry and scopes.
Every endpoint except the public catalog needs an API key sent as a Bearer token.
Authorization: Bearer <your-api-key>Key format
A key looks like this (this one is a placeholder, not a working key):
nx_live_xxxxxxxxxxxx_YOUR_SECRET_HERE| Part | Meaning |
|---|---|
nx | NEXTOREx key |
live or test | The environment the key belongs to |
| 12 characters | A non-secret prefix. It is shown in the dashboard and in /me so you can tell keys apart. |
| the rest | The secret. Shown once, never retrievable. |
Live and test environments
A key carries its environment. A NEXTOREx deployment accepts only keys of its own environment: a production deployment accepts live keys, a development or sandbox deployment accepts test keys. A key presented to the wrong environment is rejected with api_key_environment_mismatch.
The secret is shown once
When you create or rotate a key the full secret appears in the dashboard a single time. NEXTOREx keeps only a one-way hash. If you lose the secret, create a new key (or rotate) and revoke the old one.
Rotation
Rotating a key issues a new secret with exactly the same access. The old key keeps working for a grace period you choose (24 hours by default, at most 7 days; 0 revokes it immediately) so you can deploy the new secret without downtime. A rotated key can have fewer scopes than before, never more.
Revocation
Revoking a key stops it working immediately. Requests then fail with api_key_revoked.
Expiration
Keys expire. If you do not choose a date the key lasts 365 days; the longest allowed lifetime is 730 days. An expired key fails with api_key_expired. Plan a rotation before expiry.
Scopes
A scope is a ceiling on what one key may attempt. Choose the smallest set the integration needs.
| Scope | Allows |
|---|---|
crm:read / crm:write | CRM leads |
erp:read / erp:write | ERP customers and products |
education:read / education:write | Education students |
billing:read / billing:write | Your NEXTOREx subscription and invoices |
There is no wildcard scope. GET /me and the hierarchy endpoints need only a valid key. The public catalog needs no key at all.
Developer API access
Your account must have Developer API access. If access is removed (for example when a plan changes), every key stops working with developer_api_not_entitled until it is restored. The keys themselves are not deleted.
Who can create keys
Only a regular NEXTOREx user with the API key permission. The user can only create a key for a company, place in the organisation tree and role they can already reach, and the key can never be more powerful than the user who created it. Platform administrators cannot hold keys.
Failed authentication
Missing, malformed, unknown, revoked or expired keys return 401 with a WWW-Authenticate: Bearer header. Repeated failures from one address or for one key prefix are rate limited.