Authentication

AdRelay uses two layers of authentication:

API Key — Authenticates your requests to the AdRelay API
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.

curl -X GET "https://api.adrelay.dev/v1/campaigns" \
  -H "X-API-Key: your-api-key-here"

Getting Your API Key

Sign in to the AdRelay Dashboard
Navigate to Settings > API Keys
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.

curl -X POST "https://api.adrelay.dev/v1/api-keys/rotate" \
  -H "X-API-Key: $ADRELAY_API_KEY"

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

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:

Initiate — Call the authorize endpoint to get an OAuth URL
Authorize — User completes the OAuth flow in their browser
Store — AdRelay stores and manages the OAuth tokens
Refresh — Tokens are automatically refreshed before expiration

Starting the OAuth Flow

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

{
  "error": "Invalid or missing API key.",
  "code": "UNAUTHORIZED",
  "timestamp": 1711036800,
  "request_id": "req_abc123"
}

Getting Started

Guides

SDKs

API Key Authentication

Getting Your API Key

Rotating Your API Key

Security Best Practices

OAuth for Ad Platforms

Starting the OAuth Flow

Token Lifecycle

Error Codes

Example Error Response

​API Key Authentication

​Getting Your API Key

​Rotating Your API Key

​Security Best Practices

​OAuth for Ad Platforms

​Starting the OAuth Flow

​Token Lifecycle

​Error Codes

​Example Error Response

API Key Authentication

Getting Your API Key

Rotating Your API Key

Security Best Practices

OAuth for Ad Platforms

Starting the OAuth Flow

Token Lifecycle

Error Codes

Example Error Response