Connect with OAuth

A client that supports MCP authorization can sign a person in to PilotFox instead of using an API key. The person picks an organization and approves the permissions the client asks for; the client then gets an access token that acts as that person, in that organization, never beyond their current role there.

PilotFox's authorization server is built into the instance: OAuth 2.1 authorization code with PKCE, public clients only, with URL client ids (Client ID Metadata Documents) and no dynamic client registration.

DiscoveryCopy Anchor Link

A client finds everything from the MCP endpoint itself. A request without a credential is answered 401 with a challenge naming the protected-resource metadata (RFC 9728):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://pilotfox.app/.well-known/oauth-protected-resource/api/mcp"
Content-Type: application/json

{"jsonrpc":"2.0","error":{"code":-32001,"message":"missing authorization header"},"id":null}

{
  "resource": "https://pilotfox.app/api/mcp",
  "authorization_servers": ["https://pilotfox.app/api/auth"],
  "bearer_methods_supported": ["header"],
  "dpop_signing_alg_values_supported": ["EdDSA", "ES256", "ES512", "PS256", "RS256"],
  "scopes_supported": [
    "site:read", "analytics:read", "sessions:read", "users:read", "goals:read", "goals:write",
    "funnels:read", "funnels:write", "segments:read", "annotations:write", "revenue:read"
  ]
}

The authorization-server metadata names the endpoints, all under https://pilotfox.app/api/auth:

It has no registration_endpoint, and there is no client_credentials grant: every token belongs to a person. The client authentication methods are none alone, as PilotFox accepts public clients only (see Public clients only), so the metadata names no signing algorithms for client assertions. It has no introspection_endpoint either: introspection needs client credentials, which PilotFox refuses. The OpenID Connect discovery document states the same values.

Client idsCopy Anchor Link

PilotFox has to know the client before it can sign anyone in. It accepts two kinds of client id.

A URL: Client ID Metadata DocumentCopy Anchor Link

The client's id is an https URL where the client publishes a JSON document describing itself. This is the usual choice for MCP clients, and needs nothing from you. When a client presents such an id, PilotFox fetches the document and checks it:

{
  "client_id": "https://assistant.example.com/oauth/client-metadata.json",
  "client_name": "Example Assistant",
  "client_uri": "https://assistant.example.com",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

A client registered by an administratorCopy Anchor Link

A system administrator of the instance can register a client and give its id to the client's users. On pilotfox.app that is the PilotFox team; on your own instance, you. Registration is POST /api/auth/oauth2/create-client, open to system administrators only, with a signed-in session. The client must be public ("token_endpoint_auth_method": "none"); a desktop or CLI client that receives the code on a loopback address needs "application_type": "native":

curl https://pilotfox.app/api/auth/oauth2/create-client \
  -H "Cookie: $ADMIN_SESSION_COOKIE" \
  -H "Origin: https://pilotfox.app" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Internal reporting agent",
    "redirect_uris": ["http://127.0.0.1:8976/callback"],
    "application_type": "native",
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "openid offline_access site:read analytics:read goals:read goals:write"
  }'

The answer (201) carries the generated client_id. token_endpoint_auth_method must be sent as "none": any other value, or leaving it out, is refused (400 invalid_client_metadata). A client of the default application_type (web) needs https redirect URIs (400 invalid_redirect_uri otherwise). The client can then ask only for the scopes listed in its scope: an authorization asking for another comes back with error=invalid_scope.

There is no dynamic client registration: POST /api/auth/oauth2/register answers 403 "Client registration is disabled".

Public clients onlyCopy Anchor Link

Every client authenticates with PKCE alone. A client secret, a client assertion or an Authorization header sent to the token, introspection or revocation endpoint is refused with 401:

{"error":"invalid_client","error_description":"Only public clients are supported: send client_id with PKCE, no client credentials"}

What a public client sends to each endpoint:

The flowCopy Anchor Link

https://pilotfox.app/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=https%3A%2F%2Fassistant.example.com%2Foauth%2Fclient-metadata.json
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2Fcallback
  &scope=openid%20offline_access%20site%3Aread%20analytics%3Aread
  &state=af0ifjsldkj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fpilotfox.app%2Fapi%2Fmcp

curl https://pilotfox.app/api/auth/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode code="$CODE" \
  --data-urlencode redirect_uri=http://127.0.0.1:33418/callback \
  --data-urlencode client_id=https://assistant.example.com/oauth/client-metadata.json \
  --data-urlencode code_verifier="$CODE_VERIFIER" \
  --data-urlencode resource=https://pilotfox.app/api/mcp

ScopesCopy Anchor Link

The tool reference names the permission each tool needs. Only these eleven permission scopes grant anything on the MCP server.

What a token can doCopy Anchor Link

A token acts as its person, in the organization it is bound to (its org_id claim), with the scopes it was granted intersected with the person's current role in that organization. The role is read again on every request, so a promotion, a demotion or a site grant counts at once.

• Tools: the server lists the tools whose permission is in both the token's scopes and the person's role. A viewer never gets a write tool, even with goals:write in the token's scopes: viewers hold no write permission. Members, editors, admins and owners hold all three MCP write permissions.
• Restricted members (members who see only the sites granted to them) get a viewer's tool list, so no write tool, and reach only the sites granted to them.
• Sites: the organization's sites the person can see. Their own sites in another organization answer not_found: bind another token to that organization to reach them. A site made public by its owners is open to anyone, through these tools too.
• Segments: the organization's shared segments and, with segments:read, the person's own private segments.
• REST: none. An MCP access token authenticates /api/mcp only; the REST API (/api/v1) answers it 401.

See Permissions and scopes for what each role holds.

Token checksCopy Anchor Link

Access tokens are signed JWTs (typ: at+jwt), valid for one hour. On every request the MCP server checks:

1. The signature, against the instance's own key set; a token whose key id is unknown is refused at once.
2. iss is the instance's authorization server, aud includes https://pilotfox.app/api/mcp, and exp has not passed.
3. The token is still live: the PilotFox session it was issued from still exists and has not expired, the person is not banned, and the client exists and is not disabled.
4. The person is still a member of the token's organization.

How access endsCopy Anchor Link

Because the token lives and dies with the PilotFox session it came from, signing out of PilotFox in that browser disconnects every MCP client authorized from it.

To disconnect one client without signing out, the person lists their approvals with GET /api/auth/oauth2/get-consents and deletes one with POST /api/auth/oauth2/delete-consent and {"id": "…"}, both with their signed-in session. That revokes the client's refresh tokens for that organization; an access token already issued cannot be revoked and expires within the hour.

LimitsCopy Anchor Link

120 MCP requests a minute per person and client, and each tool call counts against the REST budget of the same principal. See Limits.