Authentication

All API access is authenticated using OAuth 2.0. Your app receives access tokens that are scoped to the specific permissions each merchant granted during installation. Base URL:

https://api.production.orderprotection.com

Authorization Code Flow

This is the primary flow for apps installed by merchants. When a merchant installs your app from the marketplace, OrderProtection delivers an authorization code to your redirect URI. You exchange this code for access and refresh tokens.

1. Merchant installs your app

When a merchant clicks Install on your app, they review and approve the requested scopes. OrderProtection then delivers an authorization code to your first registered redirect URI as a server-to-server GET (your endpoint must respond 2xx within 10 seconds or the install rolls back):

GET https://yourapp.example.com/callback?code=a1b2c3d4e5f6&store_id=<store id>

Consent happens inside the OrderProtection dashboard (or via the install API, where the code comes back in the response body instead) — there is no hosted /oauth/authorize web page to redirect merchants to. Don’t construct an authorize URL by convention from other OAuth providers; the code is delivered from the install/approve step. Full install reference: Installing Your App.

Parameter	Description
`code`	The authorization code to exchange for tokens
`state`	The state parameter you provided (if any), for CSRF protection

2. Exchange code for tokens

Exchange the authorization code for an access token and refresh token:

curl -X POST https://api.production.orderprotection.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "op_app_fc6767b5694ba053...",
    "client_secret": "op_secret_8915e130...",
    "code": "a1b2c3d4e5f6",
    "redirect_uri": "https://yourapp.example.com/callback"
  }'

const response = await fetch(
  "https://api.production.orderprotection.com/v1/oauth/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      client_id: "op_app_fc6767b5694ba053...",
      client_secret: "op_secret_8915e130...",
      code: "a1b2c3d4e5f6",
      redirect_uri: "https://yourapp.example.com/callback",
    }),
  }
);
const tokens = await response.json();

Token response

{
  "access_token": "op_at_af444635983c457a5e...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "op_rt_27f3894986c211168b...",
  "scope": "order:read claim:read store:read"
}

Field	Description
`access_token`	Bearer token for API calls. Prefixed with `op_at_`.
`token_type`	Always `Bearer`.
`expires_in`	Token lifetime in seconds (3600 = 1 hour).
`refresh_token`	Long-lived token to obtain new access tokens. Prefixed with `op_rt_`.
`scope`	Space-separated list of granted scopes.

PKCE support

The authorization code flow supports PKCE (Proof Key for Code Exchange) with the S256 method for enhanced security. If a code_challenge was provided during authorization, you must include the code_verifier when exchanging the code:

{
  "grant_type": "authorization_code",
  "client_id": "op_app_...",
  "client_secret": "op_secret_...",
  "code": "a1b2c3d4e5f6",
  "redirect_uri": "https://yourapp.example.com/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

Client Credentials Flow

Use this flow for server-to-server access when no user interaction is needed. This is useful for background jobs, data sync, or admin operations.

The client credentials flow requires an existing installation on the target store. A merchant must have already installed your app (granting scopes) before you can use this flow. The store_id parameter tells OrderProtection which installation to use for determining your granted scopes.

curl -X POST https://api.production.orderprotection.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "op_app_fc6767b5694ba053...",
    "client_secret": "op_secret_8915e130...",
    "store_id": "store_abc123",
    "scopes": ["order:read", "claim:read"]
  }'

const response = await fetch(
  "https://api.production.orderprotection.com/v1/oauth/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: "op_app_fc6767b5694ba053...",
      client_secret: "op_secret_8915e130...",
      store_id: "store_abc123",
      scopes: ["order:read", "claim:read"],
    }),
  }
);
const tokens = await response.json();

The scopes parameter is optional and acts as a filter. If omitted, the token will include all scopes granted by the merchant during installation.

Refreshing tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the merchant to re-authorize:

curl -X POST https://api.production.orderprotection.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "op_app_fc6767b5694ba053...",
    "client_secret": "op_secret_8915e130...",
    "refresh_token": "op_rt_27f3894986c211168b..."
  }'

The response includes a new access token and a new refresh token. Always store and use the latest refresh token — previous ones are rotated.

Revoking tokens

When a merchant disconnects your app or you need to invalidate tokens, revoke them explicitly:

curl -X POST https://api.production.orderprotection.com/v1/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "op_at_af444635983c457a5e...",
    "client_id": "op_app_fc6767b5694ba053...",
    "client_secret": "op_secret_8915e130...",
    "token_type_hint": "access_token"
  }'

Parameter	Required	Description
`token`	Yes	The token to revoke
`client_id`	Yes	Your app’s client ID
`client_secret`	Yes	Your app’s client secret
`token_type_hint`	No	Either `access_token` or `refresh_token`

Using access tokens

Include the access token in the Authorization header of every API request:

curl -X GET https://api.production.orderprotection.com/v1/orders \
  -H "Authorization: Bearer op_at_af444635983c457a5e..."

Access tokens are scoped to the permissions the merchant granted. If you attempt to access an endpoint that requires a scope the merchant did not grant, you will receive a 403 Forbidden response.

Token prefixes

OrderProtection tokens use prefixes for easy identification:

Prefix	Type
`op_at_`	Access token
`op_rt_`	Refresh token
`op_app_`	Client ID
`op_secret_`	Client secret

Getting Started

Analytics

Distribution

Reference

Authentication

Authorization Code Flow

1. Merchant installs your app

2. Exchange code for tokens

Token response

PKCE support

Client Credentials Flow

Refreshing tokens

Revoking tokens

Using access tokens

Token prefixes

​Authorization Code Flow

​1. Merchant installs your app

​2. Exchange code for tokens

​Token response

​PKCE support

​Client Credentials Flow

​Refreshing tokens

​Revoking tokens

​Using access tokens

​Token prefixes

Authorization Code Flow

1. Merchant installs your app

2. Exchange code for tokens

Token response

PKCE support

Client Credentials Flow

Refreshing tokens

Revoking tokens

Using access tokens

Token prefixes