API reference
API keys
List, create, rotate and revoke API keys.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| Identify the key in use | GET /api/whoami | read |
| List API keys | GET /api/orgs/{org}/api-keys | read |
| Create an API key | POST /api/orgs/{org}/api-keys | console only (owner) |
| Rotate an API key | POST /api/orgs/{org}/api-keys/{id}/rotate | console only (owner) |
| Revoke an API key | DELETE /api/orgs/{org}/api-keys/{id} | console only (owner) |
#Identify the key in use
GET /api/whoami
Answers which organisation the API key sent with the call belongs to, the key's name, scope and expiry, and the server's version. A client that holds nothing but a key calls this first: every other route needs the organisation slug it returns. The secret is not returned. A console session is not accepted here; it has the session route.
Who may call it: An API key with the read scope or higher.
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/whoami"
Answer (200, application/json)
A WhoAmI object.
{
"organisation": {
"slug": "acme",
"name": "Acme",
"suspended": false
},
"key": {
"id": "key_5d0b8e2f17a9",
"name": "CI pipeline",
"scope": "read",
"expiresAt": "2027-01-01T11:00:00.000Z"
},
"server": {
"version": "0.1.0",
"apiVersion": 1
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | unauthenticated | No API key was sent. |
#List API keys
GET /api/orgs/{org}/api-keys
Answers the organisation's API keys without their secrets. This is a plain list, not a paged one.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/api-keys"
Answer (200, application/json)
Every API key of the organisation.
An array of ApiKey.
[
{
"id": "key_5d0b8e2f17a9",
"name": "CI pipeline",
"prefix": "ng_Xk3p9Q",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-02T11:00:00.000Z",
"lastUsedAt": "2026-11-16T09:28:00.000Z",
"scope": "read",
"expiresAt": "2027-01-01T11:00:00.000Z",
"rotatedAt": "2026-11-01T11:00:00.000Z"
}
]
#Create an API key
POST /api/orgs/{org}/api-keys
Creates a key and answers it with its secret, once. Only an owner signed in to the console can do this, with a recent second-factor check when their account has one.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | A name to recognise the key by. 1 to 80 characters, and different from the names of the other keys in the organisation (ignoring case). |
scope | string | no | What the key may do. Default read. |
expiresInDays | integer or null | no | How many days until the key expires: a whole number from 1 to 3650. Leave out, or send null, for a key that does not expire. |
Answer (200, application/json)
A ApiKeyWithSecret object.
{
"id": "key_5d0b8e2f17a9",
"name": "CI pipeline",
"prefix": "ng_Xk3p9Q",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-02T11:00:00.000Z",
"lastUsedAt": "2026-11-16T09:28:00.000Z",
"scope": "read",
"expiresAt": "2027-01-01T11:00:00.000Z",
"rotatedAt": "2026-11-01T11:00:00.000Z",
"key": "ng_Xk3p9QvL2mT8wZr4YcB7nHs6JdF1aGe5UoKi0PqR"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 409 | duplicate_name | Another API key of the organisation already has that name. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Rotate an API key
POST /api/orgs/{org}/api-keys/{id}/rotate
Replaces the key's secret and answers the new one, once. The id, name, scope and expiry stay the same. The old secret stops working in the same moment: there is no overlap, so update whatever uses the key straight away.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Answer (200, application/json)
A ApiKeyWithSecret object.
{
"id": "key_5d0b8e2f17a9",
"name": "CI pipeline",
"prefix": "ng_Xk3p9Q",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-02T11:00:00.000Z",
"lastUsedAt": "2026-11-16T09:28:00.000Z",
"scope": "read",
"expiresAt": "2027-01-01T11:00:00.000Z",
"rotatedAt": "2026-11-01T11:00:00.000Z",
"key": "ng_Xk3p9QvL2mT8wZr4YcB7nHs6JdF1aGe5UoKi0PqR"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no API key with that id in this organisation. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Revoke an API key
DELETE /api/orgs/{org}/api-keys/{id}
Deletes the key. Requests that use it answer 401 from then on.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no API key with that id in this organisation. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Objects
The objects the operations above take and return.
#WhoAmI
The organisation and key behind the API key that made the call.
| Field | Type | Always present | Description |
|---|---|---|---|
organisation | object | yes | |
organisation.slug | string | yes | The organisation's slug: the {org} in every organisation route. |
organisation.name | string | yes | The organisation's name. |
organisation.suspended | boolean | yes | True while the workspace is suspended: reads work, changes are refused. |
key | object | yes | |
key.id | string | yes | The key's id. |
key.name | string | yes | The name given when it was created. |
key.scope | string | yes | What the key may do. One of: read, write, admin. |
key.expiresAt | string or null | yes | When it stops working. Null when it does not expire. |
server | object | yes | |
server.version | string | yes | The version of the server. |
server.apiVersion | integer | yes | The version of the API, also sent as the X-Nullgap-Api-Version header of every answer. It goes up when the API gains behaviour an older client would misread. |
#ApiKey
An API key, without its secret.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The key's id. Use it to rotate or revoke the key. |
name | string | yes | The name given when it was created. |
prefix | string | yes | The first nine characters of the key, to tell keys apart. The full key is shown only when it is created or rotated. |
createdBy | string | yes | Who created it. |
createdAt | string | yes | When it was created. |
lastUsedAt | string or null | yes | When it was last used, to the nearest minute. Null when it never was. |
scope | string | yes | What the key may do. Keys created before scopes existed read as admin. |
expiresAt | string or null | yes | When it stops working. Null when it does not expire. |
rotatedAt | string or null | yes | When its secret was last replaced. Null when it never was. |
#ApiKeyWithSecret
An API key together with its secret. This is the only time the secret is returned.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The key's id. Use it to rotate or revoke the key. |
name | string | yes | The name given when it was created. |
prefix | string | yes | The first nine characters of the key, to tell keys apart. The full key is shown only when it is created or rotated. |
createdBy | string | yes | Who created it. |
createdAt | string | yes | When it was created. |
lastUsedAt | string or null | yes | When it was last used, to the nearest minute. Null when it never was. |
scope | string | yes | What the key may do. Keys created before scopes existed read as admin. |
expiresAt | string or null | yes | When it stops working. Null when it does not expire. |
rotatedAt | string or null | yes | When its secret was last replaced. Null when it never was. |
key | string | yes | The full key. Send it as Authorization: Bearer <key>. Store it now: it cannot be read again. |
Nullgap documentation