---
title: "Exchange a hosted OAuth callback code, store the token in the configured vault, and persist a Secret Manager ref"
method: POST
path: "/connections/callback-exchange"
---

# Exchange a hosted OAuth callback code, store the token in the configured vault, and persist a Secret Manager ref

`POST /connections/callback-exchange`

## 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/connections/callback-exchange`
- Auth: HTTP bearer

## Request body

- object
  - `state` string, required
  - `code` string, required: Raw provider authorization code. It is exchanged server-side and is never returned or logged.
  - `redirect_uri` string, uri, required
  - `client_id` string: Optional override; production should use env config.
  - `code_verifier` string: PKCE verifier loaded by the Portal/connector boundary.
  - `secret_manager_resource` string: Optional Secret Manager secret resource override. Production defaults to GRAVITYADS_OAUTH_SECRET_RESOURCE_TEMPLATE and only a hash is returned.
  - `kms_key_resource` string
  - `version_alias` string

## Response `200`

OAuth token exchanged

- object
  - `status` 'connections_callback_exchange_completed', required
  - `tenant_id` string, required
  - `platform` string, required
  - `connection_id` string, required
  - `secret_ref_id` string
  - `account_sync` object
    - `status` 'pending' | 'running' | 'succeeded' | 'failed'
    - `reason` string
    - `credential_version` string
    - `discovered_count` integer
    - `saved_count` integer
    - `started_at` string
    - `completed_at` string
    - `error_code` string
    - `retryable` boolean
  - `account_upsert` object
  - `account_discovery` object
  - `reauthorization` boolean: Existing connection authorization was renewed without changing selected accounts or ETL assignments; inspect account_sync independently.
  - `next_step` string: Google renewal returns to connections; Meta may select_accounts, return_to_connections or retry_account_sync.
  - `vault` object
  - `token_response_metadata` object
  - `permission_probe` object
  - `connection` object
  - `ready_for_readonly_etl` boolean, required
  - `database_url_configured` boolean, required
  - `hosted_auth_context` object
  - `raw_authorization_code_returned` false, required
  - `raw_token_material_returned` false, required
  - `raw_secrets_returned` 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)