Nullgap.dev Docs

API reference

Connected apps (OAuth)

Connected apps (OAuth) 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
Register a clientPOST /api/oauth/registernone
Start connecting an appGET /api/oauth/authorizenone
Get tokensPOST /api/oauth/tokennone
DisconnectPOST /api/oauth/revokenone

#Register a client

POST /api/oauth/register

OAuth 2.0 Dynamic Client Registration (RFC 7591), for MCP clients that do not publish a client metadata document. Public clients only: no secret is issued, PKCE takes its place. Each redirect address must be https, or http on 127.0.0.1, [::1] or localhost; others are left out of the answer. A registration that is never used to connect is dropped after seven days. Limited to 30 registrations an hour from one address. Answers 201.

Who may call it: None. No key is needed.

Request body (application/json)

FieldTypeRequiredDescription
redirect_urisarray of stringyesWhere the authorization answer may be sent. 1 to 10.
client_namestringnoThe name the person is shown, marked as unverified.
token_endpoint_auth_methodstringnoOnly none.
grant_typesarray of stringnoMust include authorization_code.
response_typesarray of stringnoMust include code.

Example request

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris":["http://127.0.0.1:53682/callback"],"client_name":"Example Agent","token_endpoint_auth_method":"none","grant_types":["authorization_code"],"response_types":["code"]}' \
  "$NULLGAP_URL/api/oauth/register"

Answer (201, application/json)

FieldTypeAlways presentDescription
client_idstringyesThe client id to use from now on.
client_id_issued_atintegeryesWhen it was issued, in seconds since 1970.
client_namestringyesThe name as it will be shown.
redirect_urisarray of stringyes
grant_typesarray of stringyes
response_typesarray of stringyes
token_endpoint_auth_methodstringyesAlways none.
{
  "client_id": "mcpc_Zk3vQp81LmNxQm9iX2Fs",
  "client_id_issued_at": 1794744000,
  "client_name": "Example Agent",
  "redirect_uris": [
    "http://127.0.0.1:53682/callback"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none"
}

Errors specific to this call

StatusCodeWhen
400invalid_redirect_uriNo redirect address is acceptable, or more than 10 were sent.
400invalid_client_metadataThe client asked to authenticate with a secret, or for grant or response types this server does not offer.

#Start connecting an app

GET /api/oauth/authorize

The OAuth 2.1 authorization endpoint. An MCP client opens this address in the person's browser. When the request is sound the browser is sent on to the console's consent page, where the person signs in if they are not already, picks a workspace and the access to give, and approves or denies. The answer reaches the client at its redirect address with code, state and iss (RFC 9207), or with error. A request whose client or redirect address is not right is never sent to that address: the person is told on the consent page. PKCE with S256 is required, and resource must be this server's MCP address. Answers 302.

Who may call it: None. No key is needed.

Query parameters

NameTypeRequiredDescription
response_typestringyesAlways code.
client_idstringyesA client id from registration, or the https address of the client's metadata document.
redirect_uristringyesOne of the client's redirect addresses, exactly. For an address on this machine the port may differ.
code_challengestringyesThe PKCE challenge: SHA-256 of the verifier, base64url, 43 characters.
code_challenge_methodstringyesMust be S256; plain is refused.
resourcestringyesThe MCP address the token is for: <console>/mcp, or <console>/mcp/<workspace> to connect one workspace only (RFC 8707).
scopestringnoThe most access the client wants: nullgap:read, nullgap:write, nullgap:admin, space-separated. Without it, read and write. The person may give less.
statestringnoReturned unchanged with the answer.

Example request

curl -s \
  "$NULLGAP_URL/api/oauth/authorize?response_type=code&client_id=value&redirect_uri=value&code_challenge=value&code_challenge_method=S256&resource=value"

Answer (302, text/plain)

A redirect. The Location header holds the consent page, or the client's redirect address with an error.

#Get tokens

POST /api/oauth/token

The OAuth 2.1 token endpoint. authorization_code: redeem the code from the authorization answer, within one minute, once, with the PKCE verifier, the same client id, redirect address and resource. A code presented a second time ends the connection it made. refresh_token: exchange a refresh token for a new pair; the old one is spent, and presenting it again ends the connection. Every exchange checks again that the person is still a member with the role the connection needs. No client secret is accepted. Limited to 120 requests a minute from one address.

Who may call it: None. No key is needed.

Request body (application/x-www-form-urlencoded)

FieldTypeRequiredDescription
grant_typestringyesWhich exchange. One of: authorization_code, refresh_token.
client_idstringyesThe client id.
codestringnoFor authorization_code: the code.
code_verifierstringnoFor authorization_code: the PKCE verifier.
redirect_uristringnoFor authorization_code: the redirect address of the request.
refresh_tokenstringnoFor refresh_token: the refresh token.
resourcestringnoThe MCP address, as in the authorization request.

Example request

curl -s -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-binary @code.zip \
  "$NULLGAP_URL/api/oauth/token"

Answer (200, application/json)

A new access token and refresh token.

FieldTypeAlways presentDescription
access_tokenstringyesSend it as Authorization: Bearer <token> to the MCP endpoint, and nowhere else: the rest of the API refuses it.
token_typestringyesAlways Bearer.
expires_inintegeryesSeconds until the access token expires: one hour.
refresh_tokenstringyesExchange it for a new pair before or after the access token expires. Each refresh token works once; presenting a used one again ends the connection.
scopestringyesThe access the person granted, as OAuth scopes: nullgap:read, plus nullgap:write, plus nullgap:admin.
{
  "access_token": "ngmcp_at_Qm9iX2FsaWNlX3Rva2VuX2V4YW1wbGVfMDEyMzQ1Njc4OQ",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ngmcp_rt_Qm9iX2FsaWNlX3JlZnJlc2hfZXhhbXBsZV8wMTIzNDU2Nzg5",
  "scope": "nullgap:read nullgap:write"
}

Errors specific to this call

StatusCodeWhen
400invalid_grantThe code or refresh token is unknown, expired, already used, issued to another client, or the verifier does not match; or the person no longer has the access the connection needs.
400invalid_targetresource is not the one the code or connection is for.
400unsupported_grant_typegrant_type is neither of the two.
401invalid_clientA client secret was sent; this server has public clients only.

#Disconnect

POST /api/oauth/revoke

OAuth 2.0 token revocation (RFC 7009). Hand back an access or refresh token and the whole connection ends: every token of it stops working. The answer is the same whether the token was known or not.

Who may call it: None. No key is needed.

Request body (application/x-www-form-urlencoded)

FieldTypeRequiredDescription
tokenstringyesAn access or refresh token.
client_idstringnoThe client id.

Example request

curl -s -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-binary @code.zip \
  "$NULLGAP_URL/api/oauth/revoke"

Answer (200, application/json)

An empty object.

{}

Nullgap documentation