Nullgap.dev Docs

API reference

Connected apps

Connected apps in the Nullgap API.

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
Show a connection requestGET /api/oauth/consentconsole session
Approve or deny a connectionPOST /api/oauth/consentconsole session
List my connected appsGET /api/me/connected-appsconsole session
Disconnect one of my appsDELETE /api/me/connected-apps/{id}console session
List the workspace's connected appsGET /api/orgs/{org}/mcp-connectionsadmin
Set the rule for connected appsPUT /api/orgs/{org}/mcp-connections/policyconsole only (admin)
Disconnect an app from the workspaceDELETE /api/orgs/{org}/mcp-connections/{id}console only (admin)
GET /api/oauth/consent

What the console's consent page shows for an authorization request: the app, where the answer goes, and each of the signed-in person's workspaces with the most access they may give it there, or why they cannot. The query is the authorization request as the client sent it.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

FieldTypeAlways presentDescription
clientobjectno
client.namestringyesThe name the app gave itself. Unverified.
client.kindstringyesHow the app is known. One of: registered, metadata.
client.hoststring or nullyesFor an app known by its metadata document, the host the document came from.
client.redirectHoststringyesWhere the browser is sent with the answer.
client.loopbackbooleanyesTrue when the answer goes to a program on this computer.
requestedstringnoThe most the app asked for. read: read-only. write: read, and change what a member can (triage, start runs and fixes). admin: also what an admin can, never what only an owner can.
personobjectno
person.emailstringyesWho is signed in.
workspacesarray of objectno
workspaces[].slugstringyesThe workspace slug.
workspaces[].namestringyesThe workspace name.
workspaces[].rolestringyesThe person's role there. One of: owner, admin, member.
workspaces[].maxstring or nullyesThe most access the person may give here, or null when none. read: read-only. write: read, and change what a member can (triage, start runs and fixes). admin: also what an admin can, never what only an owner can.
workspaces[].blockedstring or nullyesWhy nothing may be given here: mcp_disabled, mfa_required, sso_required, org_suspended, org_deleting.
workspaces[].messagestring or nullyesThe reason, for a person.
signInFreshbooleannoFalse when the sign-in is more than 12 hours old: the person must sign in again before approving.
redirectstringnoInstead of everything else, when the request is to be refused at the client's address: where to send the browser.
{
  "client": {
    "name": "Example Agent",
    "kind": "registered",
    "host": "agent.example.com",
    "redirectHost": "127.0.0.1:53682",
    "loopback": true
  },
  "requested": "write",
  "person": {
    "email": "dev@acme.test"
  },
  "workspaces": [
    {
      "slug": "acme",
      "name": "Acme",
      "role": "member",
      "max": "write",
      "blocked": "mfa_required",
      "message": "This organisation requires multi-factor sign-in."
    }
  ],
  "signInFresh": true,
  "redirect": "http://127.0.0.1:53682/callback?error=invalid_request&iss=https%3A%2F%2Fconsole.nullgap.dev"
}

Errors specific to this call

StatusCodeWhen
400connection_request_invalidThe client is unknown, or its redirect address is not one it registered. Nobody is redirected.

#Approve or deny a connection

POST /api/oauth/consent

The person's answer on the consent page. The request is checked again from the start. Approving needs a sign-in less than 12 hours old and, on an account with a second factor, a check in the last 15 minutes. The access given is never more than the app asked for, the person's role allows (admin access needs an admin) and the workspace's rule allows. The answer says where to send the browser: the app's redirect address with a one-time code, or with error=access_denied.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Request body (application/json)

FieldTypeRequiredDescription
requeststringyesThe authorization request's query string, as the page received it.
decisionstringyesThe answer. One of: approve, deny.
workspacestringnoFor approve: the workspace slug.
accessstringnoFor approve: what to give. read: read-only. write: read, and change what a member can (triage, start runs and fixes). admin: also what an admin can, never what only an owner can.

Answer (200, application/json)

FieldTypeAlways presentDescription
redirectstringyesWhere to send the browser.
{
  "redirect": "http://127.0.0.1:53682/callback?code=ngmcp_ac_Qm9i&state=xyz&iss=https%3A%2F%2Fconsole.nullgap.dev"
}

Errors specific to this call

StatusCodeWhen
400connection_request_invalidThe client is unknown, or its redirect address is not one it registered.
403insufficient_roleMore access than the person's role or the workspace's rule allows.
403mcp_disabledThe workspace does not allow connected apps.
403reauth_requiredThe sign-in is more than 12 hours old.
403step_up_requiredThe account has a second factor and it was not checked in the last 15 minutes.
404not_foundThe person is not a member of that workspace.

#List my connected apps

GET /api/me/connected-apps

The apps the signed-in person connected, in every workspace (a single sign-on session sees its own workspace only). A plain array.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

An array of object.

[
  {
    "id": "mcg_3f9a1c0d2e4b",
    "client": {
      "name": "Example Agent",
      "kind": "registered",
      "redirectHost": "127.0.0.1:53682"
    },
    "workspace": {
      "slug": "acme",
      "name": "Acme"
    },
    "access": "write",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "lastUsedAt": "2026-11-16T09:30:00.000Z",
    "person": {
      "email": "dev@acme.test",
      "name": "Dev"
    }
  }
]

#Disconnect one of my apps

DELETE /api/me/connected-apps/{id}

Ends one of the signed-in person's connections. Every token of it stops working at once.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Path parameters

NameTypeRequiredDescription
idstringyesThe connection id from the list.

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundThe person has no connection with that id.

#List the workspace's connected apps

GET /api/orgs/{org}/mcp-connections

Every app any member connected to this workspace, with whose it is, and the workspace's rule for connecting apps. An admin signed in to the console, or an API key with the admin scope, may read it, so a security team can review connections from a script. Changing the rule or ending a connection stays in the console.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/mcp-connections"

Answer (200, application/json)

FieldTypeAlways presentDescription
policystringyesThe rule: allowed, read-only (no connection may change anything) or off.
connectionsarray of objectyes
connections[].idstringyesThe connection id, for ending it.
connections[].clientobjectyes
connections[].client.namestringyesThe name the app gave itself. Nobody has checked it.
connections[].client.kindstringyesregistered: the app registered itself with this server. metadata: its id is the address of a document it publishes, so the host of that address is real.
connections[].client.redirectHoststringyesWhere the browser was sent back to when it was approved, usually a program on the person's own computer.
connections[].workspaceobjectyes
connections[].workspace.slugstringyesThe workspace slug.
connections[].workspace.namestringyesThe workspace name.
connections[].accessstringyesWhat the connection may do. read: read-only. write: read, and change what a member can (triage, start runs and fixes). admin: also what an admin can, never what only an owner can.
connections[].createdAtstringyesWhen it was approved.
connections[].lastUsedAtstring or nullyesWhen it was last used, to the nearest minute. Null until it is used.
connections[].personobjectnoOnly in the workspace admins' list.
connections[].person.emailstringyesWhose connection it is.
connections[].person.namestringyesTheir name.
{
  "policy": "allowed",
  "connections": [
    {
      "id": "mcg_3f9a1c0d2e4b",
      "client": {
        "name": "Example Agent",
        "kind": "registered",
        "redirectHost": "127.0.0.1:53682"
      },
      "workspace": {
        "slug": "acme",
        "name": "Acme"
      },
      "access": "write",
      "createdAt": "2026-11-16T09:30:00.000Z",
      "lastUsedAt": "2026-11-16T09:30:00.000Z",
      "person": {
        "email": "dev@acme.test",
        "name": "Dev"
      }
    }
  ]
}

#Set the rule for connected apps

PUT /api/orgs/{org}/mcp-connections/policy

allowed: members may connect apps with up to their own role's access. read-only: connections may only read, existing ones included. off: no app may be connected, and every existing connection ends. Recorded in the audit log.

Who may call it: A signed-in admin or owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
policystringyesThe rule. One of: allowed, read-only, off.

Answer (200, application/json)

FieldTypeAlways presentDescription
policystringyesThe rule now. One of: allowed, read-only, off.
revokedintegeryesHow many connections were ended.
{
  "policy": "read-only",
  "revoked": 0
}

#Disconnect an app from the workspace

DELETE /api/orgs/{org}/mcp-connections/{id}

Ends any member's connection into this workspace. Every token of it stops working at once. Recorded in the audit log.

Who may call it: A signed-in admin or owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe connection id from the list.

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo connection with that id in this workspace.

Nullgap documentation