Approve or deny an MCP connector

POST

/api/mcp/consent

curl --request POST \
  --url https://example.com/api/mcp/consent \
  --header 'Content-Type: application/json' \
  --header 'Remote-User: <Remote-User>' \
  --data '{ "client_id": "example", "redirect_uri": "example", "code_challenge": "example", "code_challenge_method": "S256", "state": "example", "csrf": "example", "action": "approve", "grants": [ { "kind": "group", "target": "example", "permissions": [ "publish" ] } ], "acknowledge_global": true }'

• Your gotifacts apex (canonical base domain), fronted by your reverse proxy. Any configured alias domains serve the same API and sites, but responses (e.g. base_domain) always report the canonical domain.

Available only when GOTIFACTS_MCP_ENABLED=true. Records the user’s decision on the consent screen and answers with the URL to send the browser to (window.location.assign): the client’s redirect_uri carrying a code (approve), error=access_denied (deny), or error=invalid_scope with an error_description (invalid grants), plus the client’s state.

The grants are validated server-side: 1 to 16 grants; each kind is group or site; targets are lower-cased, trimmed of / and checked as site-path labels; permissions is non-empty and limited to the capabilities returned by GET /api/mcp/consent, which include read. A global grant (kind group, empty target) needs acknowledge_global: true.

Errors before the redirect URI is trusted (bad CSRF token, unknown client, unregistered redirect URI, malformed body) are 400 JSON.

Authorizations

• forwardAuth

Request Body^required

Media typeapplication/json

The user’s decision on the MCP consent screen.

object

client_id

required

string

redirect_uri

required

string

code_challenge

required

string

code_challenge_method

string

Allowed values: S256

state

string

csrf

required

The token from GET /api/mcp/consent.

string

action

required

string

Allowed values: approve deny

grants

Required for approve; ignored for deny.

Array<object>

>= 1 items <= 16 items

object

kind

required

string

Allowed values: group site

target

required

A group path (e.g. docs, empty = all sites) or a group/slug for a single site.

string

permissions

required

Array<string>

Allowed values: publish unpublish rollback patch purge read

acknowledge_global

Must be true when any grant is global (group kind, empty target).

boolean

Responses

200

Where to send the browser next.

Media typeapplication/json

object

redirect_url

required

The client’s redirect URI with code or error (and state) in the query.

string

Example^generated

{
  "redirect_url": "example"
}

400

Invalid request (bad path, malformed body, or missing content).

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

401

Missing or invalid credentials.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

403

Authenticated, but not permitted for this target/capability.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}