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

# Authorize Connection

> Start the OAuth flow to connect an ad platform account.

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

  ```bash cURL (with redirect URI) theme={null}
  curl -X GET "https://api.adrelay.dev/v1/connections/google/authorize?redirect_uri=https://myapp.com/callback" \
    -H "X-API-Key: $ADRELAY_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { AdRelay } from "@adrelay/sdk";

  const client = new AdRelay({ apiKey: process.env.ADRELAY_API_KEY });

  // Default — redirects to AdRelay dashboard after OAuth
  const { data: { url } } = await client.connections.getAuthUrl("google");

  // Custom — redirects to your app after OAuth
  const { data: { url: customUrl } } = await client.connections.getAuthUrl("google", {
    redirectUri: "https://myapp.com/callback",
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.adrelay.dev/v1/connections/google/authorize",
      headers={"X-API-Key": "your-api-key-here"},
      params={"redirect_uri": "https://myapp.com/callback"},
  )

  data = response.json()
  # Redirect user to data["data"]["url"]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=..."
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "INVALID_REDIRECT_URI",
      "message": "Redirect URI is not registered. Add it in your dashboard settings first.",
      "retryable": false,
      "requestId": "req_abc123"
    }
  }
  ```
</ResponseExample>

The `{platform}` path parameter accepts: `google`, `meta`, or `tiktok`.

Direct the user to the returned URL in their browser. After completing authorization, they will be redirected to your `redirect_uri` (or the AdRelay dashboard by default) with query params:

* `?success=true&platform=GOOGLE&connectionId=...` on success
* `?error=...` on failure

## Custom Redirect URIs

By default, OAuth callbacks land on the AdRelay dashboard. To redirect to your own app:

1. Register your URI via [Settings](https://app.adrelay.dev/settings) or the [Redirect URIs API](/api-reference/redirect-uris/list)
2. Pass `redirect_uri` as a query parameter when calling authorize

Localhost URIs (ports 3000–3005, 5173, 8000, 8080) are pre-registered for development — no setup needed.

<Info>
  The `redirect_uri` only controls the final hop (AdRelay → your app). The platform-side OAuth callback (Google/Meta/TikTok → AdRelay) stays the same.
</Info>


## OpenAPI

````yaml GET /v1/connections/google/authorize
openapi: 3.1.0
info:
  title: Adrelay API
  version: 0.1.0
  description: >-
    Unified Ad Platform API — proxy and normalize campaigns across Google Ads,
    Meta, TikTok, and more.
servers:
  - url: https://api.adrelay.dev/v1
    description: Production
  - url: http://localhost:3001
    description: Local
security: []
paths:
  /v1/connections/google/authorize:
    get:
      summary: Start Google Ads OAuth
      description: Redirects to Google OAuth consent screen.
      parameters:
        - schema:
            type: string
          required: false
          name: accountId
          in: query
      responses:
        '302':
          description: Redirect to Google OAuth
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - apiKey: []
components:
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            platform:
              type: string
            retryable:
              type: boolean
            requestId:
              type: string
              format: uuid
            platformError:
              $ref: '#/components/schemas/PlatformErrorDetail'
          required:
            - code
            - message
            - retryable
            - requestId
      required:
        - error
    ErrorCode:
      type: string
      enum:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMITED
        - RATE_LIMIT_EXCEEDED
        - PLATFORM_ERROR
        - NOT_SUPPORTED
        - TOKEN_EXPIRED
        - INTERNAL_ERROR
    PlatformErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        field:
          type: string
      required:
        - message
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````