API keys

5 endpoints in this family.

List recent API calls

GET/api/v1/api-requests

Every call made to /api/v1 with one of your account's keys over the last 30 days: method, address, status, error code, duration, and the client the call acted on (null for account-level calls such as /tenants or /keys). Newest first. Use it to see why a call failed without asking us.

A key that is not pinned sees every call and may narrow them with clientId (or the Nodium-Tenant header); a key pinned to a client sees only the calls made on that client. Neither bodies, headers nor query strings are kept. A call refused because the key itself was wrong is not listed: we cannot tell whose it was.

Query parameters

apiKeyIdstring
Only calls made with this key.
clientIdstring
Only calls made on this client (id). Ignored for a pinned key.
errorsOnlyboolean
true keeps only calls that did not succeed (status 400 and above).
limitinteger
Page size, 1 to 100. Default 50.
cursorstring
The nextCursor of the previous page.

Response

A page of calls, newest first.

data.itemsApiRequest[]
The calls.
data.nextCursorstring
Pass it as cursor for the next page; null at the end.
data.hasMoreboolean
Whether another page exists.

curl https://nodium.io/api/v1/api-requests \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "items": [ {} ], "nextCursor": "…", "hasMore": true }}

List the API keys of your account

GET/api/v1/keys

Every key of your account, active ones first. A key belongs to the account: without a clientId it acts on every client (the Nodium-Tenant header names one; without it, the call acts on "My company"); with a clientId it is pinned to that client and cannot leave it.

Only the public prefix is returned — Nodium keeps a hash of each secret, never the secret itself. Requires a key that is not pinned to a client.

Response

The keys of your account, without their secrets.

data.itemsApiKey[]
The keys, active ones first.

Refusals

403all_clients_requiredThe key is pinned to a client.

curl https://nodium.io/api/v1/keys \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{ "data": { "items": [ {} ] }}

Create an API key

POST/api/v1/keys

Creates another key for your account — for key rotation, or to give a separate system its own key. Without clientId, the key acts on every client of the account; with it, the key is pinned to that client: it acts there without the Nodium-Tenant header, and naming another client answers 404.

The response carries the secret once and never again: store it now.

Body

labelstring
A name for you, shown in Nodium.
clientIdstring
Pin the key to this client: its id, or your externalId.
expiresInDaysinteger
The key stops working after this many days (1 to 3650). Absent: it never expires, unless the key making the call expires — a key never outlives the key that creates it. Past its date it answers 401 api_key_expired.

Response

The key and its secret — shown only here.

data.keyApiKey
The key.
data.tokenstring
The secret, nod_…. Shown only here.

Refusals

403all_clients_requiredThe key is pinned to a client.
404tenant_not_found`clientId` names no client of your account.
422invalid_request`expiresInDays` is not a whole number of days between 1 and 3650.

curl -X POST https://nodium.io/api/v1/keys \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{    "label": "Billing system",    "clientId": "cust_1042",    "expiresInDays": 90  }'

Response

200 OK

{  "data": {    "key": {      "id": "…",      "label": "…",      "keyPrefix": "…",      "clientId": "…",      "clientName": "…",      "isActive": true,      "createdBy": "…",      "lastUsedAt": "…",      "revokedAt": "…",      "expiresAt": "…",      "createdAt": "…"    },    "token": "…"  }}

Revoke an API key

DEL/api/v1/keys/{id}

Revokes a key of your account at once: its next call is refused. The key stays listed, revoked, as a trace.

A key revoking itself must say so with ?confirmSelf=true — otherwise the call answers 409 own_key, so that a rotation script that picks the wrong id does not lock itself out.

Path parameters

idstring
The key id.

Query parameters

confirmSelfboolean
Required, true, when the key revokes itself.

Response

The revoked key.

data.revokedboolean
Always true.
data.keyApiKey
The key, now revoked.

Refusals

403all_clients_requiredThe key is pinned to a client.
409own_keyThe key is revoking itself: repeat with `?confirmSelf=true`.
409already_revokedThe key was already revoked.

curl -X DELETE https://nodium.io/api/v1/keys/<id> \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{  "data": {    "revoked": true,    "key": {      "id": "…",      "label": "…",      "keyPrefix": "…",      "clientId": "…",      "clientName": "…",      "isActive": true,      "createdBy": "…",      "lastUsedAt": "…",      "revokedAt": "…",      "expiresAt": "…",      "createdAt": "…"    }  }}

Get the key making the call

GET/api/v1/keys/current

Tells a key what it is, without listing the others: its name, the account it belongs to, the client it is pinned to, and when it stops working. Any key can call it.

Use it to check a key you were just given: a key that acts for every client of your account is pinned: false.

Response

The key that made the call: id, name, account, pinned client, expiry.

data.idstring
The key id.
data.labelstring
The name given to the key, possibly empty.
data.accountIdstring
The account the key belongs to.
data.accountNamestring
The name of that account.
data.pinnedboolean
True when the key is pinned to one client and cannot leave it; false when it acts on every client of the account.
data.clientobject
The client the key is pinned to: id, name, isHome (true for "My company"); null when the key is not pinned.
data.expiresAtstring
ISO 8601 date after which the key answers 401 api_key_expired, or null: it never expires.

Refusals

404not_foundThe call was made with a console session, not an API key.

curl https://nodium.io/api/v1/keys/current \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK

{  "data": {    "id": "…",    "label": "…",    "accountId": "…",    "accountName": "…",    "pinned": true,    "client": {},    "expiresAt": "…"  }}