Skip to main content

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.

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

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

EventBehavior
Initial authorizationTokens stored securely by AdRelay
Token near expirationAutomatically refreshed using refresh token
Refresh token expiredConnection status set to REVOKED; re-authorization required
User revokes accessConnection status set to REVOKED on next sync

​
Error Codes

Status CodeErrorDescription
401UNAUTHORIZEDMissing or invalid API key. Verify the X-API-Key header is present and correct.
403FORBIDDENAPI 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.
429RATE_LIMITEDToo 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"
}