Nullgap.dev Docs

Developers

API keys

Create, scope, rotate and revoke the keys that scripts, pipelines and coding agents use to call the Nullgap API.

An API key lets a program call the Nullgap API, the MCP server included, as your organisation. For a coding agent you use yourself, connecting it in the browser is simpler and needs no key: see MCP server. A key belongs to exactly one organisation and has one of three scopes. This page covers the life of a key; the API overview covers how to send it, errors, paging and rate limits.

#Create a key

Only an owner can create, rotate or revoke keys, and only in the console: no API key can manage API keys. If your account has multi-factor sign-in, you are asked for a fresh code unless you entered one in the last 15 minutes. Every member can see the list of keys, without the secrets.

  1. Open Settings, then the Access tab, and find API keys.
  2. Choose Create key.
  3. Fill in the dialog (the fields are described below).
  4. Choose Create. The dialog Copy your new key now shows the key.
FieldWhat to enter
NameWhat will use the key, for example CI pipeline. Up to 80 characters. The name is what the audit log shows, so make it recognisable.
What the key may doRead, Write or Admin. See scopes. Read is selected to begin with.
ExpiresAfter 30, 90, 180 or 365 days, after a number of days you choose (1 to 3650), or never. 90 days is selected to begin with.

A key starts with ng_ and is 43 characters long. The list shows its first nine characters so you can tell keys apart.

#Scopes

Each scope includes the one before it.

ScopeWhat the key may do
readEvery GET that an ordinary member may make: findings and their evidence, exports, reviews, pentests and their logs, reports, repositories, applications, schedules, custom checks, the skill catalogue and skill runs, integrations (never their secrets), usage, the audit log and the list of members. Plus the two POST requests below.
writeEverything a read key may do, plus what an ordinary member may change: request a review of a pull request, change a finding's state (one at a time or in bulk), add a note to a finding, bring back a held-back finding, start a fix run for a finding or for a pentest's dependency advisories, file a finding as a Jira or Linear issue, edit or regenerate an application's context, check a skill's text, upload a file for a comparison, and start or cancel a skill run.
adminEverything a write key may do, plus what an admin may do without a fresh sign-in check: start, cancel and retest pentests, manage pentest schedules, add, change and remove repositories, manage applications, automations and custom checks, switch skills on and off and manage custom skills, change organisation settings, connect and disconnect Slack notifications, Jira and Linear, change, test and remove outbound webhook endpoints, share a report, invite people and remove members who are not owners, verify and export the audit log, and list and retry background jobs.

#The two POSTs a read key may make

A read key is refused on every request that is not a GET, with two exceptions that only compute an answer and change nothing:

RequestWhat it does
POST /api/orgs/:org/pentests/estimateMeasures the code in scope and returns what a pentest would be charged. Starts nothing.
POST /api/orgs/:org/dependencies/checkReturns a verdict for each package version you send. See the package check API.

#What a refusal looks like

StatusCodeMeaning
401invalid_api_keyThe key is unknown, was revoked, or was replaced by a rotation.
401expired_api_keyThe key is past its expiry.
403insufficient_scopeA read key tried to change something ("This API key is read-only"), or a read or write key called an admin route ("This API key does not have the admin scope").
403forbiddenThe action is one no key can do ("API keys cannot do this. Sign in to the console.").
403org_suspendedThe workspace is suspended and the request would change something.
404not_foundThe organisation in the path is not the key's organisation.

#What no key can ever do

A key is never an owner, whatever its scope, and some actions need a person who has just been checked. These are refused for every key:

  • Create, rotate or revoke API keys.
  • Export or erase the organisation's data.
  • Configure, test or remove single sign-on, verify its domains, and create or remove the SCIM token.
  • Connect GitLab, Bitbucket Cloud, Azure DevOps or GitHub Enterprise Server, or generate a connection's webhook secret. Confirming with GitHub that you administer an installation also needs a signed-in person.
  • Add an outbound webhook endpoint or rotate its signing secret.
  • Set up the Slack assistant, replace its signing secret or remove it, and confirm a Slack link.
  • Change a member's role, sign everyone out, or switch the organisation's multi-factor requirement on or off.
  • Open, read, answer, resolve or reopen a support request, or let Nullgap support view the workspace. Support is a conversation with a person. See the support channel.
  • Skip a step of the Getting started guide, or mark its welcome page as read.
  • Anything on a personal account: passkeys, authenticators, sessions.

#Another organisation, and suspended workspaces

  • Another organisation. A key used on any organisation but its own gets 404 not_found with "Organisation not found". It is the same answer as for an organisation that does not exist, so a key cannot be used to find out which organisations there are. The hosted MCP endpoint answers 403 instead; see MCP server.
  • A suspended workspace. Keys keep working for reads, and for the two POST requests a read key may make. Every request that would change something is refused with 403 org_suspended.

#Expiry

  • A key with an expiry stops working at that moment and answers 401 expired_api_key. It stays in the list, struck through and marked Expired, until you revoke it.
  • The list shows the expiry date and warns when it is close.
  • An expiry cannot be changed afterwards. Rotating a key keeps its expiry date; to get a longer life, create a new key.
  • A key created through the console with Never, and any key created before expiries existed, does not expire.

#Rotate a key

Choose Rotate next to the key. Rotation gives the key a new secret and keeps everything else: its id, name, scope and expiry date. The new secret is shown once.

The old secret stops working in the same moment. There is no overlap, so plan it:

  1. Create a second key with the same scope.
  2. Move your pipeline or tool to the second key and check that it works.
  3. Revoke the first key.

Or, where a short interruption is acceptable, rotate and update the stored secret straight away.

#Revoke a key

Choose Revoke next to the key. The key is deleted and stops working at once; requests with it answer 401 invalid_api_key. This cannot be undone.

Revoke a key as soon as you suspect it has leaked, then look at what it did: actions taken with a key are recorded in the audit log with the actor api-key:<key name>.

#Last used

The list shows when each key was last used, or "never used". The time is updated at most once a minute, so it tells you whether a key is still in use, not the time of its latest request. A key that has not been used for a long time is a candidate for revoking.

Creating, rotating and revoking a key are themselves recorded in the audit log as apikey.created (with the scope and expiry), apikey.rotated and apikey.revoked.

#Storing keys in CI

  • Put the key in your CI system's secret store (an encrypted secret in GitHub Actions, a masked and protected variable in GitLab CI) and read it from the environment. Never commit it, and do not pass it on a command line that is echoed into the log.
  • Use one key per pipeline or tool, named after it. Then revoking one does not break the others, and the audit log tells them apart.
  • Give it the smallest scope that does the job. Checking packages, exporting findings and gating a release need only read. See CI examples.
  • Give it an expiry and put the rotation in your calendar.
  • Do not expose the key to builds of pull requests from forks. Anyone who can change the pipeline definition there can print it.

The samples in these pages use three environment variables:

export NULLGAP_URL="https://nullgap.example"   # the address of your Nullgap console, no trailing slash
export NULLGAP_ORG="acme"                      # your organisation's slug
export NULLGAP_API_KEY="ng_..."                # from your secret store

To check a key, list the keys of its organisation. Any scope may do this, and the answer never contains a secret:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/api-keys"
[
  {
    "id": "key_4d1a7c9e2b30",
    "name": "CI pipeline",
    "prefix": "ng_Zk3Qw9",
    "createdBy": "dana@acme.example",
    "createdAt": "2026-11-02T10:12:00.000Z",
    "lastUsedAt": "2026-11-16T09:30:00.000Z",
    "scope": "read",
    "expiresAt": "2027-01-31T10:12:00.000Z",
    "rotatedAt": null
  }
]

The routes are listed in the API keys reference.

Nullgap documentation