Choose your authentication model
CortexHub has separate credentials for the MCP gateway data plane and the Platform API control plane. Choose the path that matches where the agent runs and which identity it acts for.
Person in Claude / ChatGPT / Cursor?
-> Interactive Member OAuth (Authorization Code + PKCE)
Your server runs for a CortexHub member?
-> Programmatic Member Credential (client_credentials)
Your server has its own users who are not CortexHub members?
-> Organisation Gateway Key + end-user attestation
Your automation provisions organisations and governance?
-> Platform API control-plane OAuth (client_credentials)
Choose a path
| Use case | Surface | Credential and grant | Identity headers |
|---|---|---|---|
| A person connects Claude, Cursor, ChatGPT, or another MCP client | MCP gateway | Interactive Member OAuth (Authorization Code + PKCE) | Authorization, X-CortexHub-Agent |
| A server-side process acts as one CortexHub member | MCP gateway | Programmatic Member Credential (client_credentials) | Authorization, X-CortexHub-Agent |
| Your backend acts for users who do not have CortexHub accounts | MCP gateway | Organisation Gateway Key with per-call end-user attestation | X-CortexHub-Key, X-CortexHub-Agent, X-CortexHub-End-User-Subject |
| An SDK Org Agent runs in your application | MCP gateway | Organisation Gateway Key bound to the Org Agent | X-CortexHub-Key, X-CortexHub-Agent |
| Your automation manages organisations and governance | Platform API | Control-plane OAuth (client_credentials) | Authorization: Bearer |
All paths reach the same governance pipeline. The credential authenticates the caller; the agent identity and organization policy decide what the call may do.
MCP gateway: interactive Member OAuth
Interactive MCP clients add https://mcp.cortexhub.ai/v1/mcp, discover the OAuth endpoints, and open a browser for the member to sign in and approve access. The client completes Authorization Code + PKCE and sends:
Authorization: Bearer <access_token>
X-CortexHub-Agent: <agent reference>
Use this path for Claude, ChatGPT, Cursor, and other MCP clients where a person is present. Each client registers its own gateway identity in the member's active organisation. This is different from the programmatic member credential below.
MCP gateway: programmatic Member Credential
Create a member MCP OAuth client in CortexHub Cloud → Account → MCP API access when a server-side process should act as that member. Exchange the client id and secret with the client_credentials grant at /v1/mcp/oauth/token.
This grant authenticates the member identity already bound to the client. It does not perform an interactive sign-in and does not replace Authorization Code + PKCE.
MCP gateway: org key
Use an organisation gateway key when your backend owns the end-user account system or when an SDK Org Agent runs as the organisation. Send the key and a stable agent reference on every call:
X-CortexHub-Key: cxh_mcpk_<id>_<secret>
X-CortexHub-Agent: <agent reference or cxh_agent_* id>
X-CortexHub-End-User-Subject: <opaque caller-side user id>
X-CortexHub-End-User-Subject is required for backend calls acting for external end users and lets policies and audit records attribute the action correctly. An SDK Org Agent uses the same key with its registered agent identity. A hosted Org Agent does not need a runtime key because it runs inside CortexHub.
Never send vendor credentials or an org key to a model or chat transcript. Store them in your runtime's secret manager and rotate them through the organization controls.
Platform API: control-plane OAuth
The Platform API at https://api.cortexhub.ai uses a separate control-plane OAuth client with the minimum scopes required for organisation management. It uses client_credentials to create and configure organisation resources, governance groups, tool access, integrations, and credentials. It is not the MCP tool invocation endpoint.
Token refresh and failures
Refresh MCP OAuth credentials after a 401. For org keys, rotate the key and update the runtime secret. Treat 403 as a governance or scope decision and inspect the returned error code and request id.