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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Show a connection request | GET /api/oauth/consent | console session |
| Approve or deny a connection | POST /api/oauth/consent | console session |
| List my connected apps | GET /api/me/connected-apps | console session |
| Disconnect one of my apps | DELETE /api/me/connected-apps/{id} | console session |
| List the workspace's connected apps | GET /api/orgs/{org}/mcp-connections | admin |
| Set the rule for connected apps | PUT /api/orgs/{org}/mcp-connections/policy | console only (admin) |
| Disconnect an app from the workspace | DELETE /api/orgs/{org}/mcp-connections/{id} | console only (admin) |
#Show a connection request
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)
| Field | Type | Always present | Description |
|---|---|---|---|
client | object | no | |
client.name | string | yes | The name the app gave itself. Unverified. |
client.kind | string | yes | How the app is known. One of: registered, metadata. |
client.host | string or null | yes | For an app known by its metadata document, the host the document came from. |
client.redirectHost | string | yes | Where the browser is sent with the answer. |
client.loopback | boolean | yes | True when the answer goes to a program on this computer. |
requested | string | no | The 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. |
person | object | no | |
person.email | string | yes | Who is signed in. |
workspaces | array of object | no | |
workspaces[].slug | string | yes | The workspace slug. |
workspaces[].name | string | yes | The workspace name. |
workspaces[].role | string | yes | The person's role there. One of: owner, admin, member. |
workspaces[].max | string or null | yes | The 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[].blocked | string or null | yes | Why nothing may be given here: mcp_disabled, mfa_required, sso_required, org_suspended, org_deleting. |
workspaces[].message | string or null | yes | The reason, for a person. |
signInFresh | boolean | no | False when the sign-in is more than 12 hours old: the person must sign in again before approving. |
redirect | string | no | Instead 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
| Status | Code | When |
|---|---|---|
| 400 | connection_request_invalid | The 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)
| Field | Type | Required | Description |
|---|---|---|---|
request | string | yes | The authorization request's query string, as the page received it. |
decision | string | yes | The answer. One of: approve, deny. |
workspace | string | no | For approve: the workspace slug. |
access | string | no | For 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)
| Field | Type | Always present | Description |
|---|---|---|---|
redirect | string | yes | Where 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
| Status | Code | When |
|---|---|---|
| 400 | connection_request_invalid | The client is unknown, or its redirect address is not one it registered. |
| 403 | insufficient_role | More access than the person's role or the workspace's rule allows. |
| 403 | mcp_disabled | The workspace does not allow connected apps. |
| 403 | reauth_required | The sign-in is more than 12 hours old. |
| 403 | step_up_required | The account has a second factor and it was not checked in the last 15 minutes. |
| 404 | not_found | The 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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The connection id from the list. |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The 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
| 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/mcp-connections"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
policy | string | yes | The rule: allowed, read-only (no connection may change anything) or off. |
connections | array of object | yes | |
connections[].id | string | yes | The connection id, for ending it. |
connections[].client | object | yes | |
connections[].client.name | string | yes | The name the app gave itself. Nobody has checked it. |
connections[].client.kind | string | yes | registered: 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.redirectHost | string | yes | Where the browser was sent back to when it was approved, usually a program on the person's own computer. |
connections[].workspace | object | yes | |
connections[].workspace.slug | string | yes | The workspace slug. |
connections[].workspace.name | string | yes | The workspace name. |
connections[].access | string | yes | What 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[].createdAt | string | yes | When it was approved. |
connections[].lastUsedAt | string or null | yes | When it was last used, to the nearest minute. Null until it is used. |
connections[].person | object | no | Only in the workspace admins' list. |
connections[].person.email | string | yes | Whose connection it is. |
connections[].person.name | string | yes | Their 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
policy | string | yes | The rule. One of: allowed, read-only, off. |
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
policy | string | yes | The rule now. One of: allowed, read-only, off. |
revoked | integer | yes | How 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The connection id from the list. |
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No connection with that id in this workspace. |
Nullgap documentation