> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrelay.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Ad Accounts

> Connect Google Ads, Meta Ads, and TikTok Ads accounts via OAuth.

Before you can manage campaigns on a platform, you need to connect your ad account for that platform. Each platform uses OAuth to grant AdRelay access to your ad accounts.

## OAuth Flow by Platform

### Google Ads

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/connections/google_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

**Scopes requested:** Google Ads API read/write access. The user must have a Google Ads manager or standard account.

### Meta Ads

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/connections/meta_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

**Scopes requested:** `ads_management`, `ads_read`. The user must be an admin or advertiser on the Meta Business account.

### TikTok Ads

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/connections/tiktok_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

**Scopes requested:** Campaign management read/write. The user must have access to a TikTok Ads Manager account.

## Completing the OAuth Flow

Each authorize endpoint returns a JSON response with a redirect URL:

```json theme={null}
{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...",
  "platform": "google_ads"
}
```

Direct the user to the `authorize_url` in their browser. After granting access, they will be redirected back to AdRelay, and the connection will be established automatically.

## Syncing Accounts

After connecting a platform, trigger a sync to pull in account data:

```bash theme={null}
curl -X POST "https://api.adrelay.dev/v1/connections/sync" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

This refreshes the connection's account data and updates the connection status. You should sync after initial connection and periodically to keep data fresh.

## Connection Statuses

| Status    | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `ACTIVE`  | Connection is healthy. Tokens are valid and API calls will succeed.                                      |
| `PENDING` | OAuth flow has been initiated but not yet completed by the user.                                         |
| `REVOKED` | Access has been revoked by the user or tokens have expired beyond refresh. Re-authorization is required. |
| `ERROR`   | An error occurred with the connection. Check the connection details for more information.                |

## Listing Connections

View all your connected accounts:

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/connections" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

```json theme={null}
{
  "connections": [
    {
      "id": "conn_abc123",
      "platform": "google_ads",
      "status": "ACTIVE",
      "label": "Main Google Account",
      "remote_account_id": "123-456-7890",
      "created_at": "2026-03-01T12:00:00Z",
      "last_synced_at": "2026-03-21T08:00:00Z"
    },
    {
      "id": "conn_def456",
      "platform": "meta_ads",
      "status": "ACTIVE",
      "label": null,
      "remote_account_id": "act_987654321",
      "created_at": "2026-03-05T10:00:00Z",
      "last_synced_at": "2026-03-21T08:00:00Z"
    }
  ]
}
```

## Updating a Connection

You can update a connection's label to help identify it:

```bash theme={null}
curl -X PATCH "https://api.adrelay.dev/v1/connections/conn_abc123" \
  -H "X-API-Key: $ADRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "US Google Ads Account"}'
```

## Removing a Connection

Delete a connection when you no longer need it. This revokes AdRelay's access tokens for that platform account.

```bash theme={null}
curl -X DELETE "https://api.adrelay.dev/v1/connections/conn_abc123" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

<Warning>
  Deleting a connection does not delete campaigns on the platform. It only removes AdRelay's access to manage them.
</Warning>