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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Register a client | POST /api/oauth/register | none |
| Start connecting an app | GET /api/oauth/authorize | none |
| Get tokens | POST /api/oauth/token | none |
| Disconnect | POST /api/oauth/revoke | none |
#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)
| Field | Type | Required | Description |
|---|---|---|---|
redirect_uris | array of string | yes | Where the authorization answer may be sent. 1 to 10. |
client_name | string | no | The name the person is shown, marked as unverified. |
token_endpoint_auth_method | string | no | Only none. |
grant_types | array of string | no | Must include authorization_code. |
response_types | array of string | no | Must 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)
| Field | Type | Always present | Description |
|---|---|---|---|
client_id | string | yes | The client id to use from now on. |
client_id_issued_at | integer | yes | When it was issued, in seconds since 1970. |
client_name | string | yes | The name as it will be shown. |
redirect_uris | array of string | yes | |
grant_types | array of string | yes | |
response_types | array of string | yes | |
token_endpoint_auth_method | string | yes | Always 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_redirect_uri | No redirect address is acceptable, or more than 10 were sent. |
| 400 | invalid_client_metadata | The 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
| Name | Type | Required | Description |
|---|---|---|---|
response_type | string | yes | Always code. |
client_id | string | yes | A client id from registration, or the https address of the client's metadata document. |
redirect_uri | string | yes | One of the client's redirect addresses, exactly. For an address on this machine the port may differ. |
code_challenge | string | yes | The PKCE challenge: SHA-256 of the verifier, base64url, 43 characters. |
code_challenge_method | string | yes | Must be S256; plain is refused. |
resource | string | yes | The MCP address the token is for: <console>/mcp, or <console>/mcp/<workspace> to connect one workspace only (RFC 8707). |
scope | string | no | The most access the client wants: nullgap:read, nullgap:write, nullgap:admin, space-separated. Without it, read and write. The person may give less. |
state | string | no | Returned 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)
| Field | Type | Required | Description |
|---|---|---|---|
grant_type | string | yes | Which exchange. One of: authorization_code, refresh_token. |
client_id | string | yes | The client id. |
code | string | no | For authorization_code: the code. |
code_verifier | string | no | For authorization_code: the PKCE verifier. |
redirect_uri | string | no | For authorization_code: the redirect address of the request. |
refresh_token | string | no | For refresh_token: the refresh token. |
resource | string | no | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
access_token | string | yes | Send it as Authorization: Bearer <token> to the MCP endpoint, and nowhere else: the rest of the API refuses it. |
token_type | string | yes | Always Bearer. |
expires_in | integer | yes | Seconds until the access token expires: one hour. |
refresh_token | string | yes | Exchange 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. |
scope | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_grant | The 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. |
| 400 | invalid_target | resource is not the one the code or connection is for. |
| 400 | unsupported_grant_type | grant_type is neither of the two. |
| 401 | invalid_client | A 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)
| Field | Type | Required | Description |
|---|---|---|---|
token | string | yes | An access or refresh token. |
client_id | string | no | The 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