Guide
Authentication and permissions
Understand tenant identity, product scope and the human approval boundary before connecting an agent.
Public research, private workspaces
These guides, API specifications and MCP contract files are public documentation. They contain no advertiser data and grant no buying authority.
Production API calls use verified Bearer credentials bound to a user and advertiser organization. Resource ownership is checked on each request; foreign or out-of-product resource IDs return 404.
curl --fail-with-body "$ADBUY_API_URL/api/v1/auth/context" \
-H "Authorization: Bearer $ADBUY_API_TOKEN"REST API credentials
There is no self-service API key or long-lived personal access token. Sign in through the normal account flow. A direct REST integration uses the access_token from its authenticated Supabase human session; the API verifies the exact API audience and derives workspace identity from trusted claims.
The project publishable key configures a Supabase client; it does not authenticate a customer request. Never send a Supabase secret, service-role key, Stripe key or MCP OAuth token as an API credential. Keep session and refresh credentials private; do not copy them into chat, URLs or source control.
With an already signed-in Supabase client, verify access using the read-only auth/context endpoint before creating anything. The SDK manages session refresh; retrieve the current access token for each request rather than keeping a pasted token. A 401 means sign-in must be renewed or the token has the wrong audience.
// supabase is your integration’s already authenticated Supabase client.
const { data: { session }, error } = await supabase.auth.getSession();
if (error || !session) throw new Error("Sign in to continue.");
const response = await fetch(`${ADBUY_API_URL}/api/v1/auth/context`, {
headers: { Authorization: `Bearer ${session.access_token}` },
});
if (!response.ok) throw new Error("Check your sign-in and API audience.");
const context = await response.json();Connect a hosted MCP client
- Obtain the deployment's exact HTTPS /mcp resource URL. Do not infer a live endpoint from a product name or a documentation example.
- Use the client's remote MCP connection flow. The configured OAuth issuer supplies sign-in, workspace-bound consent and PKCE.
- The MCP resource validates tenant, user, original client, product and channel scope. It exchanges the grant for a separate API credential and checks the delegated identity against /api/v1/auth/context.
- Never use a shared static bearer token for a public multi-tenant service or forward a human browser session as an agent credential.
Choose a registered assistant
The AdBuyMCP Supabase deployment disables dynamic client registration. A server URL alone is insufficient: the assistant also needs its registered OAuth client identity and exact redirect URL. The connection guide reads published public client IDs; they identify the application and are not passwords or buying authority.
For Claude web and Desktop, use the published Claude client ID, choose “Sign in now” and “Use your own OAuth client”, and leave the client secret blank. Team and Enterprise organization owners add the connector before members connect. Enable it in the conversation after sign-in.
Claude Code needs a separate public client with its exact fixed http://localhost:PORT/callback URL. Use the command with both --client-id and --callback-port only after that pair is published. Do not reuse the Claude web or dashboard buyer client for another callback.
ChatGPT and other assistants require their own registration. Give the platform operator the assistant name and exact callback URL displayed by that client. Do not supply a password or session token. Until registration and real client acceptance are complete, compatibility is not a verified connection.
Verify and recover your connection
| What you see | Next step |
|---|---|
| Connected | Ask for get_platform_info and list_personas. Platform information is public; listing your personas verifies authenticated workspace access. An empty list is valid for a new workspace. |
| Dynamic registration unsupported | Select the pre-registered OAuth client settings. If no client ID is published for this assistant, request registration from the platform operator. |
| Redirect URI mismatch | Check the exact registered callback, including hostname, path and port. For Claude Code, use the published fixed callback port. Do not broaden the redirect allowlist. |
| 401 or sign-in required | Reconnect through the assistant’s OAuth sign-in. A human API token and an MCP OAuth token have different audiences and cannot be substituted. |
| Wrong workspace or missing approval | Review the signed-in account and workspace consent. Approve the exact requested action in the workspace; reconnecting cannot grant human approval authority. |
| Connection interrupted | Retry a read after reconnecting. Check the current state of a submitted campaign or booking before resubmitting a mutation. |
What permissions mean
| Boundary | Behavior |
|---|---|
| Tenant | Every private resource belongs to the authenticated advertiser. |
| Product and channels | DOOHMCP permits DOOH; CTVMCP permits CTV. Signed entitlements can narrow the deployment further. |
| Human permissions | Approving authority and reconciling uncertain outcomes require the specific human permission listed on the endpoint. |
| Agent mandate | Allowed actions and budget bound what an agent may propose and execute. A mandate does not replace an exact approval. |
| Execution binding | Consequential MCP mutations carry the approved execution step and action digest, bound to the actual request. |
Current limits
Authorization combines signed claims, resource ownership, product/channel restrictions and action approvals. The public MCP OAuth resource scope is not a separate read/write scope for every individual tool.
A published OAuth registration establishes client configuration. Successful sign-in, consent, refresh and authenticated tool calls in that actual assistant still require separate acceptance; a public tool list does not prove them.