# auth.md

Agent authentication and registration for PaidSync, in one place for AI agents and MCP clients.

PaidSync is the MCP server that runs paid media: 430+ tools across 13 platforms (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Snapchat Ads, Reddit Ads, Pinterest Ads, Microsoft Ads, ChatGPT Ads, Google Tag Manager, Google Analytics 4, Google Search Console, Google Merchant Center). Every write action is approval-gated.

## Audience

AI agents and MCP clients (Claude, ChatGPT, Gemini, Perplexity, Cursor, Windsurf, Claude Code) and autonomous services that connect to PaidSync to read and operate ad accounts on a user's behalf.

## MCP endpoint

- Primary: `https://paidsync.ai/mcp`
- Alternates: `https://mcp.paidsync.ai/mcp`, `https://api.paidsync.ai/mcp`
- Transport: streamable-http. An MCP `initialize` handshake is required before `tools/call`.
- Server card: `https://paidsync.ai/.well-known/mcp/server-card.json`

## Authentication methods

PaidSync accepts two credential types.

1. OAuth 2.1 (authorization code + PKCE) - for AI clients and agents acting on a user's behalf.
2. API key (`ps_live_...`) - for server-to-server calls. Presented as the `api_key` query parameter (not a Bearer header). Generate one in the PaidSync dashboard at `https://paidsync.ai/dashboard`.

Bearer access tokens from the OAuth flow are presented in the `Authorization: Bearer` header on MCP calls.

## OAuth 2.1 endpoints (live)

The authorization server is `api.paidsync.ai`.

- Authorization endpoint: `https://api.paidsync.ai/authorize`
- Token endpoint: `https://api.paidsync.ai/token`
- Registration endpoint: `https://api.paidsync.ai/register`
- UserInfo endpoint: `https://api.paidsync.ai/userinfo`
- PKCE: required (`S256`)
- Token endpoint auth method: `none` (public client + PKCE)
- Scopes: `openid`, `email`, `profile`, `ads`, `mcp`, `read`, `write`
- Discovery: `https://paidsync.ai/.well-known/oauth-authorization-server`, `https://paidsync.ai/.well-known/oauth-protected-resource`, `https://paidsync.ai/.well-known/openid-configuration`

## Dynamic client registration (RFC 7591, live)

Agents may register a client programmatically. No pre-approval is required for the standard MCP connect flow.

- Endpoint: `POST https://api.paidsync.ai/register`
- Body: `application/json` with `client_name` and `redirect_uris`
- Response: `201 Created` with a `client_id` (public client, used with PKCE)

Example:

```
POST https://api.paidsync.ai/register
Content-Type: application/json

{ "client_name": "your-agent", "redirect_uris": ["https://your-app.example/callback"] }
```

Registering a client does not grant access to any ad account. The end user still completes the OAuth authorization and connects each platform (Google, Meta, LinkedIn, TikTok, and the rest) before any data is read or any change is proposed. Every write is approval-gated.

For managed or partner-vetted credentials (higher limits, enterprise onboarding), contact `partnerships@paidsync.ai`.

## What is behind auth

Once authenticated, an agent reaches 430+ tools across the 13 platforms through one MCP connection: account audits, wasted-spend detection, conversion-tracking setup (GTM, GA4, server-side), cross-platform reporting, and approval-gated execution. The full tool registry is returned by `tools/list` over the authenticated MCP connection; it is intentionally not published statically.

## Related discovery

- `https://paidsync.ai/AGENTS.md`, `https://paidsync.ai/.well-known/agents.md`
- `https://paidsync.ai/.well-known/agent-auth.json`
- `https://paidsync.ai/llms.txt`, `https://paidsync.ai/llms-full.txt`
- `https://paidsync.ai/.well-known/security.txt`

## Contact

- Partnerships and managed credentials: `partnerships@paidsync.ai`
- Security: `security@paidsync.ai`
- Support: `support@paidsync.ai`