Authentication - Sagepilot Docs

Sagepilot MCP supports two authentication modes.

Mode	Use when	Credential
Hosted OAuth	The client can open a Sagepilot browser sign-in flow.	No token to copy. The user signs in and approves access.
API token	The client cannot complete OAuth, or you are running private server-side automation.	`Authorization: Bearer sp_...`

For ChatGPT, Claude, Codex, and similar hosted clients, start with Hosted connectors.

API token authentication

Use this only when hosted OAuth is not available.

Open Sagepilot

Go to API Details

Open Settings -> API Details -> API client v2.

Create an API client

Create a new API client with the access your MCP client needs, then copy the sp_... token. It is shown once.

Send the token to MCP

Pass the token as an Authorization header.

Authorization: Bearer sp_your_token

Some MCP clients also support X-API-Key: sp_your_token. Prefer the Authorization header unless your client requires a separate API-key header field.

Treat sp_... API client tokens as secrets. Do not commit them to source control or expose them in client-side code.

Analytics and product access

Your connection needs the scope and dataset for each tool it calls. get_connection_info returns the resolved workspace, permissions, and dataset grants so you can check the connection before requesting a report.

Task	Scope	Dataset
Attributed revenue and estimated ROAS through `query_analytics` or `get_journey_analytics`	`analytics.query`	`marketing_attribution`
Template-category delivery through `query_analytics`	`analytics.query`	`outbound_messages`
Campaign/journey ID lookup through `search_analytics_entities`	`analytics.query`	The tool’s selected `marketing_attribution` or `outbound_messages` dataset.
List journeys or inspect a journey flow	`journeys:read`	`journeys`
List campaigns or inspect a lifetime campaign overview	`campaigns:read`	`campaigns`

For API-client analytics access, select analytics.query and the required analytics datasets when configuring your client. Analytics grants cover reports and name lookup; they do not include journey flows or campaign configuration. Use Hosted OAuth for product tools when the API-client setup does not offer the corresponding scopes, subject to your workspace role and permissions. If an existing OAuth connection lacks a required capability, reconnect and approve access again, then check get_connection_info. Reconnecting does not expand your Sagepilot role. If access still fails, ask your workspace administrator to review your permissions. See Journey and campaign tools for examples and Find entity IDs for the equivalent REST lookup.

​API token authentication

​Analytics and product access

API token authentication

Analytics and product access