Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Identify the key in useGET /api/whoamiread
List API keysGET /api/orgs/{org}/api-keysread
Create an API keyPOST /api/orgs/{org}/api-keysconsole only (owner)
Rotate an API keyPOST /api/orgs/{org}/api-keys/{id}/rotateconsole only (owner)
Revoke an API keyDELETE /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

StatusCodeWhen
401unauthenticatedNo 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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
namestringyesA name to recognise the key by. 1 to 80 characters, and different from the names of the other keys in the organisation (ignoring case).
scopestringnoWhat the key may do. Default read.
expiresInDaysinteger or nullnoHow 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

StatusCodeWhen
409duplicate_nameAnother API key of the organisation already has that name.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundThere is no API key with that id in this organisation.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundThere is no API key with that id in this organisation.
403step_up_requiredYour 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.

FieldTypeAlways presentDescription
organisationobjectyes
organisation.slugstringyesThe organisation's slug: the {org} in every organisation route.
organisation.namestringyesThe organisation's name.
organisation.suspendedbooleanyesTrue while the workspace is suspended: reads work, changes are refused.
keyobjectyes
key.idstringyesThe key's id.
key.namestringyesThe name given when it was created.
key.scopestringyesWhat the key may do. One of: read, write, admin.
key.expiresAtstring or nullyesWhen it stops working. Null when it does not expire.
serverobjectyes
server.versionstringyesThe version of the server.
server.apiVersionintegeryesThe 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.

FieldTypeAlways presentDescription
idstringyesThe key's id. Use it to rotate or revoke the key.
namestringyesThe name given when it was created.
prefixstringyesThe first nine characters of the key, to tell keys apart. The full key is shown only when it is created or rotated.
createdBystringyesWho created it.
createdAtstringyesWhen it was created.
lastUsedAtstring or nullyesWhen it was last used, to the nearest minute. Null when it never was.
scopestringyesWhat the key may do. Keys created before scopes existed read as admin.
expiresAtstring or nullyesWhen it stops working. Null when it does not expire.
rotatedAtstring or nullyesWhen 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.

FieldTypeAlways presentDescription
idstringyesThe key's id. Use it to rotate or revoke the key.
namestringyesThe name given when it was created.
prefixstringyesThe first nine characters of the key, to tell keys apart. The full key is shown only when it is created or rotated.
createdBystringyesWho created it.
createdAtstringyesWhen it was created.
lastUsedAtstring or nullyesWhen it was last used, to the nearest minute. Null when it never was.
scopestringyesWhat the key may do. Keys created before scopes existed read as admin.
expiresAtstring or nullyesWhen it stops working. Null when it does not expire.
rotatedAtstring or nullyesWhen its secret was last replaced. Null when it never was.
keystringyesThe full key. Send it as Authorization: Bearer <key>. Store it now: it cannot be read again.

Nullgap documentation