---
title: "Build hosted OAuth authorization URL with PKCE"
method: POST
path: "/oauth/authorization-start"
---

# Build hosted OAuth authorization URL with PKCE

`POST /oauth/authorization-start`

## Request

- Base URL: `https://api.gravityads.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gravityads.dev/oauth/authorization-start`
- Auth: HTTP bearer

## Request body

- object
  - `platform` 'google' | 'meta' | 'microsoft' | 'bing' | 'tiktok' | 'pinterest' | 'linkedin', required
  - `redirect_uri` string, uri, required
  - `client_id` string: Hosted OAuth app client id. Prefer env in production.
  - `connection_id` string
  - `account_hint` string
  - `access_mode` 'read_only' | 'controlled_write'
  - `scopes` string[]
  - `authorization_purpose` 'standard' | 'new_creative' | 'page_discovery' | 'instagram_identity' | 'threads_identity': Meta controlled_write purposes: new_creative adds pages_read_engagement and pages_show_list; identity discovery also requests pages_manage_ads for promote_pages, with instagram_basic and threads_business_basic added by the selected identity purpose.

## Response `200`

OAuth authorization URL

- object
  - `schema_version` 'gravityads.hosted_oauth_authorization_start.v1', required
  - `status` 'oauth_authorization_start_ready', required
  - `tenant_id` string, required
  - `platform` string, required
  - `connection_id` string, required
  - `authorization_url` string, required
  - `state` string, required
  - `state_claims` object
  - `pkce` object, required
    - `method` 'S256' | 'provider_not_supported'
    - `provider_supported` boolean
    - `code_challenge` string
    - `code_verifier_secret_target` string
    - `code_verifier_returned` boolean
  - `scopes` string[], required
  - `authorization_purpose` 'standard' | 'new_creative' | 'page_discovery' | 'instagram_identity' | 'threads_identity'
  - `access_mode` 'read_only' | 'controlled_write'
  - `developer_token_required_in_connector` boolean
  - `writes_platform` false, required
  - `raw_token_forwarded_to_adapter` false, required

---

[API](https://skmtc.dev/gravityads/apis/gravityads-api.md) · [All operations](https://skmtc.dev/gravityads/apis/gravityads-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gravityads/apis/gravityads-api/revisions/124cd07d534d?raw)