OnwardOnward
  • Public docs
  • Internal docs
  • Guides
  • Public API Reference
  • Internal documentation
Information
Users API
Account Connection API
    Complete OAuth account linkingpostStart OAuth account linkingpost
Events API
Rewards API
Quest chain API
Schemas
Onward Public API
Onward Public API

Account Connection API

Connect platform and advertiser user accounts.


Complete OAuth account linking

POST
https://api.onwardinc.net
/v1/users/connect-account
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 evaluated immediately after the accounts are linked. See the Account linking guide for the complete redirect flow.

Complete OAuth account linking › Request Body

Payload of POST /v1/users/connect-account.
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 account is connected.

Complete OAuth account linking › Responses

The advertiser account was connected to the Onward user.

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","processed_outbox_record_ids":[101,102]}
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", "processed_outbox_record_ids": [ 101, 102 ] } }
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 › 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
POST/v1/account/start-connect
curl https://api.onwardinc.net/v1/account/start-connect \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --header 'X-API-Secret: <api-key>' \ --data '{ "platform_user_id": "usr_abc123", "quest_chain_id": "550e8400-e29b-41d4-a716-446655440000", "redirect_url": "https://yourplatform.com/oauth/callback" }'
Example Request Body
{ "platform_user_id": "usr_abc123", "quest_chain_id": "550e8400-e29b-41d4-a716-446655440000", "redirect_url": "https://yourplatform.com/oauth/callback" }
json
Example Responses
{ "success": true, "data": { "redirect_url": "https://www.example.com/path/to/resource" } }
json
application/json

Users APIEvents API