> ## 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.

# Authentication

> How to authenticate with the AdRelay API using API keys and connect ad accounts via OAuth.

AdRelay uses two layers of authentication:

1. **API Key** -- Authenticates your requests to the AdRelay API
2. **OAuth** -- Connects your ad platform accounts (Google, Meta, TikTok)

## API Key Authentication

Every request to the AdRelay API must include your API key in the `X-API-Key` header.

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns" \
  -H "X-API-Key: your-api-key-here"
```

### Getting Your API Key

1. Sign in to the [AdRelay Dashboard](https://app.adrelay.dev)
2. Navigate to **Settings > API Keys**
3. Copy your API key

### Rotating Your API Key

If your API key is compromised, rotate it immediately. The old key will be invalidated and a new one will be issued.

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

<Warning>
  Rotating your API key immediately invalidates the previous key. Update all applications using the old key before rotating.
</Warning>

### Security Best Practices

* Store your API key in environment variables, never in source code
* Rotate your key periodically and immediately if compromised
* Use separate API keys for development and production environments

## OAuth for Ad Platforms

To manage campaigns on a specific platform, you must first connect that platform's ad account via OAuth. AdRelay handles the full OAuth lifecycle:

1. **Initiate** -- Call the authorize endpoint to get an OAuth URL
2. **Authorize** -- User completes the OAuth flow in their browser
3. **Store** -- AdRelay stores and manages the OAuth tokens
4. **Refresh** -- Tokens are automatically refreshed before expiration

### Starting the OAuth Flow

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

Replace `{platform}` with one of: `google_ads`, `meta_ads`, `tiktok_ads`.

The response includes a redirect URL that the user should open in their browser to complete authorization.

### Token Lifecycle

| Event                 | Behavior                                                      |
| --------------------- | ------------------------------------------------------------- |
| Initial authorization | Tokens stored securely by AdRelay                             |
| Token near expiration | Automatically refreshed using refresh token                   |
| Refresh token expired | Connection status set to `REVOKED`; re-authorization required |
| User revokes access   | Connection status set to `REVOKED` on next sync               |

## Error Codes

| Status Code | Error          | Description                                                                                                                                      |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`       | `UNAUTHORIZED` | Missing or invalid API key. Verify the `X-API-Key` header is present and correct.                                                                |
| `403`       | `FORBIDDEN`    | API key is valid but does not have permission for this operation. This may occur if your plan does not include access to the requested resource. |
| `429`       | `RATE_LIMITED` | Too many requests. See the `Retry-After` header for when to retry.                                                                               |

### Example Error Response

```json theme={null}
{
  "error": "Invalid or missing API key.",
  "code": "UNAUTHORIZED",
  "timestamp": 1711036800,
  "request_id": "req_abc123"
}
```