API keys

An API key authorises an external system, for example your ERP, to use the exoCortex REST API v1: open tickets, read their status and add comments. Each key belongs to a tenant and sees only that tenant’s tickets.

Creating a key

1. In exoCortex Core, open Integrations → API keys. You need an administrative role, for example it_admin or integration_admin.
2. Give the key a name that says who uses it, for example “ERP connector”.
3. Choose the scopes, that is, what the key can do (see below).
4. Copy the full key and save it in the secrets manager of the system that will use it. exoCortex shows it only once and keeps only a fingerprint: if you lose it, you create a new key.

The key has the form nhk.<keyid>.<secret>. The keyid identifies the key in the list; only you keep the secret.

Scopes

Scope	What it allows
tickets:create	Open tickets
tickets:read	Read the status of a ticket
tickets:comment	Add comments to a ticket
tickets:*	All ticket operations
*	Everything the v1 API allows

Give each key only the scopes it needs. A key without scopes has full access to the v1 API: this is allowed, but not recommended.

Using the key

Send the key in the Authorization header of every request:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

Alternatively, you can use the X-NH-API-Key header. You do not specify the tenant: exoCortex derives it from the key.

Always use Idempotency-Key when you open a ticket: if you repeat the request with the same idempotency key, you get the ticket already created instead of a duplicate.

Rate limits

Each key has a request limit: the default is 600 requests every 60 seconds. Every response tells you where you stand:

Header	Meaning
RateLimit-Limit	Requests allowed in the window
RateLimit-Remaining	Requests still available
RateLimit-Reset	Seconds until the new window
Retry-After	Only with a 429 response: seconds to wait before retrying

Errors

v1 API errors return a JSON with ok: false, a readable message in error and a stable code in code. Base your client logic on the code, not on the message.

code	HTTP status	What to do
missing_api_key	401	Add the Authorization header
invalid_api_key	401	Check the key: it may be wrong or revoked
insufficient_scope	403	Add the scope shown in required_scope to the key
api_key_disabled	403	The key is disabled: use an active key
validation_error	400	Fix the field shown in field
not_found	404	The ticket does not exist or does not belong to the key’s tenant
rate_limited	429	Wait the number of seconds shown in Retry-After
ingest_failed	500	Retry with the same Idempotency-Key

exoCortex may add new codes: if you receive one you do not know, decide based on the HTTP status.

Revoking a key

From Integrations → API keys you revoke a key when a system no longer uses it or if you think it has been exposed. Revocation is immediate. The list also shows when each key was last used: this helps you find inactive keys.

Deprecated nh_… keys

Keys in the old nh_… format work until 30 June 2027. Responses to these keys contain the Deprecation and Sunset headers. To migrate, create an nhk. key with the scopes you need, update the system that uses it, then revoke the old key.