Account Connection API

Connect platform and advertiser user accounts.

Complete OAuth account linking

POST

https://api.onwardinc.net

/v1/account/connect

X-API-Key (header)

+X-API-Secret (header)

Advertiser

Completes an account connection initiated through the Onward OAuth flow. The connection token must belong to the calling advertiser. Optional retroactive events are stored and queued for asynchronous processing through the outbox atomically with the account link. See the Account linking guide for the complete redirect flow.

Complete OAuth account linking › Request Body

Payload of POST /v1/account/connect.

token

string · minLength: 1 · maxLength: 4096 · required

Short-lived account connection token received through the Onward OAuth flow.

advertiser_user_id

string · minLength: 1 · maxLength: 255 · required

Identifier of the user in the advertiser's own system.

object

Advertiser-defined attributes to store with the account connection.

object[] · maxItems: 100

Up to 100 historical events to evaluate after the advertiser account is linked.

Complete OAuth account linking › Responses

The advertiser account was connected to the Onward user.

success

boolean · enum · required

Enum values:

object · required

Result of a successfully completed account connection.

Example: {"user_connected":true,"user_id":"6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31","platform_user_id":"platform-user-456","advertiser_user_id":"advertiser-user-123","redirect_url":"https://platform.example/connection-complete","event_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}

POST/v1/account/connect

curl https://api.onwardinc.net/v1/account/connect \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "token": "eyJhbGciOiJIUzI1NiJ9.account-connection-token",
  "advertiser_user_id": "advertiser-user-123",
  "metadata": {
    "loyalty_tier": "gold"
  },
  "retro_events": [
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z"
    }
  ]
}'

Example Request Body

{
  "token": "eyJhbGciOiJIUzI1NiJ9.account-connection-token",
  "advertiser_user_id": "advertiser-user-123",
  "metadata": {
    "loyalty_tier": "gold"
  },
  "retro_events": [
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z"
    }
  ]
}

json

Example Responses

{
  "success": true,
  "data": {
    "user_connected": true,
    "user_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31",
    "platform_user_id": "platform-user-456",
    "advertiser_user_id": "advertiser-user-123",
    "redirect_url": "https://platform.example/connection-complete",
    "event_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

json

application/json

deprecated

Complete OAuth account linking

POST

https://api.onwardinc.net

/v1/users/connect-account

X-API-Key (header)

+X-API-Secret (header)

Advertiser

Complete OAuth account linking › Request Body

Payload of POST /v1/account/connect.

token

string · minLength: 1 · maxLength: 4096 · required

Short-lived account connection token received through the Onward OAuth flow.

advertiser_user_id

string · minLength: 1 · maxLength: 255 · required

Identifier of the user in the advertiser's own system.

object

Advertiser-defined attributes to store with the account connection.

object[] · maxItems: 100

Up to 100 historical events to evaluate after the advertiser account is linked.

Complete OAuth account linking › Responses

The advertiser account was connected to the Onward user.

success

boolean · enum · required

Enum values:

object · required

Result of a successfully completed account connection.

POST/v1/users/connect-account

curl https://api.onwardinc.net/v1/users/connect-account \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "token": "eyJhbGciOiJIUzI1NiJ9.account-connection-token",
  "advertiser_user_id": "advertiser-user-123",
  "metadata": {
    "loyalty_tier": "gold"
  },
  "retro_events": [
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z"
    }
  ]
}'

Example Request Body

{
  "token": "eyJhbGciOiJIUzI1NiJ9.account-connection-token",
  "advertiser_user_id": "advertiser-user-123",
  "metadata": {
    "loyalty_tier": "gold"
  },
  "retro_events": [
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z"
    }
  ]
}

json

Example Responses

{
  "success": true,
  "data": {
    "user_connected": true,
    "user_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31",
    "platform_user_id": "platform-user-456",
    "advertiser_user_id": "advertiser-user-123",
    "redirect_url": "https://platform.example/connection-complete",
    "event_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

json

application/json

Start OAuth account linking

POST

https://api.onwardinc.net

/v1/account/start-connect

X-API-Key (header)

+X-API-Secret (header)

Publisher

Creates a short-lived account-connection token for a platform user and returns the advertiser redirect URL. See the Account linking guide for the complete redirect flow.

Start OAuth account linking › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

Enum values:

web

ios

android

background

x-onward-user-agent

string

The end user's own User-Agent, forwarded verbatim. Platform servers call Onward server-to-server, so the request's own User-Agent is the platform's HTTP client, not the user's.

Start OAuth account linking › Request Body

Payload of POST /v1/account/start-connect.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

User's ID on the platform.

Example: usr_abc123

quest_chain_id

string · uuid · required

Quest chain ID which initiates the account connection.

Example: 550e8400-e29b-41d4-a716-446655440000

redirect_url

string · uri · minLength: 1 · required

Where to send the user after the connection completes (success or error)

Example: https://yourplatform.com/oauth/callback

Start OAuth account linking › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Users API Events API

Complete OAuth account linking

POST

https://api.onwardinc.net

/v1/account/connect

X-API-Key (header)

+X-API-Secret (header)

Advertiser

Complete OAuth account linking › Request Body

Payload of POST /v1/account/connect.

token

string · minLength: 1 · maxLength: 4096 · required

Short-lived account connection token received through the Onward OAuth flow.

advertiser_user_id

string · minLength: 1 · maxLength: 255 · required

Identifier of the user in the advertiser's own system.

object

Advertiser-defined attributes to store with the account connection.

object[] · maxItems: 100

Up to 100 historical events to evaluate after the advertiser account is linked.

Complete OAuth account linking › Responses

The advertiser account was connected to the Onward user.

success

boolean · enum · required

Enum values:

object · required

Result of a successfully completed account connection.

Complete OAuth account linking

POST

https://api.onwardinc.net

/v1/users/connect-account

X-API-Key (header)

+X-API-Secret (header)

Advertiser

Complete OAuth account linking › Request Body

Payload of POST /v1/account/connect.

token

string · minLength: 1 · maxLength: 4096 · required

Short-lived account connection token received through the Onward OAuth flow.

advertiser_user_id

string · minLength: 1 · maxLength: 255 · required

Identifier of the user in the advertiser's own system.

object

Advertiser-defined attributes to store with the account connection.

object[] · maxItems: 100

Up to 100 historical events to evaluate after the advertiser account is linked.

Complete OAuth account linking › Responses

The advertiser account was connected to the Onward user.

success

boolean · enum · required

Enum values:

object · required

Result of a successfully completed account connection.

Start OAuth account linking

POST

https://api.onwardinc.net

/v1/account/start-connect

X-API-Key (header)

+X-API-Secret (header)

Publisher

Creates a short-lived account-connection token for a platform user and returns the advertiser redirect URL. See the Account linking guide for the complete redirect flow.

Start OAuth account linking › Headers

x-onward-channel

string · enum

Optional. Where the end user is: web, ios or android. Without it the action is attributed to the channel of the user's last GET /v1/quest-chains/active call.

Enum values:

web

ios

android

background

x-onward-user-agent

string

The end user's own User-Agent, forwarded verbatim. Platform servers call Onward server-to-server, so the request's own User-Agent is the platform's HTTP client, not the user's.

Start OAuth account linking › Request Body

Payload of POST /v1/account/start-connect.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

User's ID on the platform.

Example: usr_abc123

quest_chain_id

string · uuid · required

Quest chain ID which initiates the account connection.

Example: 550e8400-e29b-41d4-a716-446655440000

redirect_url

string · uri · minLength: 1 · required

Where to send the user after the connection completes (success or error)

Example: https://yourplatform.com/oauth/callback

Start OAuth account linking › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required