# 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: 630+ tools across 14 platforms (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Snapchat Ads, Reddit Ads, Pinterest Ads, Microsoft Ads, X Ads, ChatGPT Ads, Google Tag Manager, Google Analytics 4, Google Search Console, Google Merchant Center). Creates are previewed with a dry run and destructive changes need an explicit confirm; in the PaidSync workspace every write is also held as an approval card.

## 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_` followed by 64 hex characters) - for server-to-server calls. Send it in the `Authorization: Bearer` header or the `x-api-key` header, and only in a header. Never put the key in a URL; query strings end up in server, proxy and client logs. An API key cannot apply changes to Google Ads (reads and dry runs only); on the other platforms it can, under the same checks as an OAuth session. 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`
- 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. Creates preview with a dry run and destructive changes need an explicit confirm; over MCP, your client's own confirmation prompt is the human check.

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

## What is behind auth

Once authenticated, an agent reaches 630+ tools across the 14 platforms through one MCP connection: account audits, wasted-spend detection, conversion-tracking setup (GTM, GA4, server-side), cross-platform reporting, and guarded execution (dry run on creates, explicit confirm on destructive changes). 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`