Quick Start: The OAuth Flow

Approved apps connect to merchants with the OAuth 2.0 authorization-code flow. The Credentials tab shows a Quick start card with these steps filled in with your client_id, your first redirect URI, and your granted scopes. Each block has a copy button.

The card also lists Client ID, Granted scopes (plus offline_access), and Registered redirect URIs.

Endpoints

Purpose	Production	Staging
Authorize	https://api.triplewhale.com/api/v2/auth/oauth2/auth	https://staging.api.triplewhale.com/api/v2/auth/oauth2/auth
Token (exchange and refresh)	https://api.triplewhale.com/api/v2/auth/oauth2/token	https://staging.api.triplewhale.com/api/v2/auth/oauth2/token
Revoke	https://api.triplewhale.com/api/v2/auth/oauth2/revoke	https://staging.api.triplewhale.com/api/v2/auth/oauth2/revoke
Granted shops	https://api.triplewhale.com/api/v2/developers/oauth2/granted-shops	https://staging.api.triplewhale.com/api/v2/developers/oauth2/granted-shops
Push ad data (ads:write)	https://api.triplewhale.com/api/v2/data-in/ads	https://staging.api.triplewhale.com/api/v2/data-in/ads
Push email and SMS data (email-sms:write)	https://api.triplewhale.com/api/v2/data-in/email-sms	https://staging.api.triplewhale.com/api/v2/data-in/email-sms

Examples below use production. For staging, use the staging host from the table.

1. Send the Merchant to the Authorize URL

Text

https://api.triplewhale.com/api/v2/auth/oauth2/auth?response_type=code
  &client_id=<client_id>
  &redirect_uri=<url-encoded redirect_uri>
  &scope=<url-encoded "scope1 scope2 offline_access">
  &state=<random_state>

• redirect_uri must match one of the app's registered redirect URIs, character for character.
• scope is a space-separated list of your granted scopes. Include offline_access to receive a refresh token.
• state is a random value you generate and check when the merchant comes back.

The merchant signs in to Triple Whale, picks the shop or shops to connect, and approves the scopes. They are redirected to your redirect_uri with code and state query parameters.

2. Exchange the Code for Tokens

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/auth/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=<authorization_code>' \
  -d 'redirect_uri=<redirect_uri>' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<client_secret>'

The response contains access_token, refresh_token (when offline_access was requested), and expires_in. Access tokens are short-lived (under an hour). Store the refresh token.

3. Refresh the Access Token

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/auth/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=<refresh_token>' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<client_secret>'

Revoke a Token

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/auth/oauth2/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=<refresh_token>' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<client_secret>'

Call the API

Send the access token as a bearer token. Listing the shops the merchant granted is the quickest check that a token works:

Bash

curl 'https://api.triplewhale.com/api/v2/developers/oauth2/granted-shops' \
  -H 'Authorization: Bearer <access_token>'

Apps approved for ads:write also see a Push ad data to Triple Whale sample on the Quick start card:

Bash

curl -X POST 'https://api.triplewhale.com/api/v2/data-in/ads' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"shop":"<shop_domain>","data":[]}'

shop must be one of the shops returned by granted-shops. The row schema for data is in the Data-In API. Rows are attributed to your provider id.

See API Endpoints for OAuth Apps for what each endpoint returns.

📘

Try It Without Writing Code

The Playground tab runs steps 1 to 3 and the granted-shops call from your browser. See Testing with the Playground.

Best Practices

• Always check state on the callback.
• Treat the refresh token as a long-lived secret for that merchant. Encrypt it at rest.
• If a refresh returns 401, send the merchant through the authorize step again. That response means the merchant disconnected your app, or your client secret was rotated.