Discovery

Four machine-readable documents describe the gateway to tools that have to configure themselves. All four are public and cached for five minutes; only the per-resource protected-resource document depends on a workspace.

They are served both under the versioned prefix and at the root of the gateway host:

GET https://gateway.praxsuite.com/openapi.json
GET https://gateway.praxsuite.com/api/v1/gateway/openapi.json

Either works.

openapi.json

An OpenAPI 3.1 description of the data plane — /{workspaceId}/schema and /{workspaceId}/query — with both security schemes declared: an API key header, and OAuth2 with the gateway:read and gateway:write scopes.

{
  "openapi": "3.1.0",
  "info": { "title": "Praxsuite DataEngine Gateway", "version": "1.0.0" },
  "servers": [{ "url": "https://gateway.praxsuite.com" }],
  "security": [{ "oauth2": ["gateway:read"] }, { "apiKey": [] }]
}

The servers entry is the authoritative base URL for the deployment you fetched it from — a dedicated deployment returns its own host here. If you are generating a client and want one fact to build it on, this is that fact.

oauth-protected-resource

GET /.well-known/oauth-protected-resource/{workspaceId}/{resource}
GET /.well-known/oauth-protected-resource

RFC 9728 protected-resource metadata. This is the document the `401` points at, and therefore the first one an MCP client fetches:

WWW-Authenticate: Bearer realm="Praxsuite Gateway", resource_metadata="https://gateway.praxsuite.com/.well-known/oauth-protected-resource/{workspaceId}/mcp"

It describes the resource the client just failed to reach, and names the authorization server that guards it:

{
  "resource": "https://gateway.praxsuite.com/{workspaceId}/mcp",
  "authorization_servers": ["https://identity.praxsuite.com"],
  "scopes_supported": ["gateway:read", "gateway:write"],
  "bearer_methods_supported": ["header"]
}

The {resource} segment is the data-plane route the client was calling — mcp, query, schema and the rest. Anything outside that set is a 404, so this cannot be used to mint a metadata document for an arbitrary path. The root form, with no workspace, describes the gateway as a whole and exists for clients that probe before they have ever seen a 401.

oauth-authorization-server

GET /api/v1/gateway/oauth-authorization-server
GET /.well-known/oauth-authorization-server

RFC 8414 authorization-server metadata — the second hop. The client reaches it by following authorization_servers out of the document above, not directly from the 401.

{
  "issuer": "…",
  "authorization_endpoint": "…/api/v1/oauth/authorize",
  "token_endpoint": "…/api/v1/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["gateway:read", "gateway:write"]
}

Authorization code with PKCE, no client secret. The issuer is the identity service, not the gateway — the gateway is the resource server.

There is no registration_endpoint: dynamic client registration is not offered. A connector is registered in the workspace, so a client cannot bring itself online unattended.

ai-plugin.json

GET /api/v1/gateway/ai-plugin.json
GET /.well-known/ai-plugin.json

The legacy ChatGPT plugin manifest. It points at openapi.json for the API surface and at the OAuth endpoints above for authentication, and it mentions the MCP endpoint in its model description.

Kept for tools that still read it. For anything new, MCP is the route.

See also

• MCP — the endpoint these documents are mostly there to help a client find

• Authentication — the WWW-Authenticate header that starts the discovery chain