Authentication & OAuth

Overview

Every app interaction with merchant data goes through OAuth. The flow is:

1. Merchant clicks "Install" on your app listing
2. Mercentia redirects them to your redirect_uri with an authorization code
3. Your app exchanges the code for an access token and refresh token
4. You use the access token in API calls via the Authorization: Bearer header
5. When the access token expires (24h), refresh it using the refresh token

OAuth 2.0 + PKCE Flow

1. Generate PKCE Challenge

Before redirecting the merchant, generate a code verifier and challenge:

import crypto from 'crypto';

// Generate a random code verifier (43-128 chars)
const codeVerifier = crypto.randomBytes(32).toString('base64url');

// Create S256 challenge
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// Store codeVerifier in your session — you'll need it in step 3

2. Authorization Request

GET /oauth/authorize
  ?client_id=sf_app_abc123
  &redirect_uri=https://myapp.com/auth/callback
  &scope=read_products,read_orders,read_customers
  &state=random_csrf_token_from_your_session
  &response_type=code
  &code_challenge={codeChallenge}
  &code_challenge_method=S256

3. Handle Callback

After the merchant approves, Mercentia redirects to your redirect_uri:

GET https://myapp.com/auth/callback
  ?code=sf_auth_xxxxx
  &state=random_csrf_token_from_your_session
  &store_id=uuid_of_merchants_store

4. Token Exchange

Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "sf_app_abc123",
  "client_secret": "your_client_secret",
  "code": "sf_auth_xxxxx",
  "redirect_uri": "https://myapp.com/auth/callback",
  "code_verifier": "original_code_verifier_from_step_1"
}

5. Token Response

{
  "access_token": "sf_at_xxxxx",
  "refresh_token": "sf_rt_xxxxx",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read_products,read_orders,read_customers",
  "store_id": "merchant_store_uuid"
}

Scopes

Request only the scopes your app actually needs (least-privilege principle):

Token Management

Access Tokens

• Expire after 24 hours
• Use in Authorization: Bearer {token} header
• Include X-Store-Id: {store_id} header with every request
• Are scoped — only grant access to the permissions the merchant approved

Refresh Tokens

• Expire after 90 days
• Single-use — each refresh gives you a new refresh token
• If a refresh token is used twice, all tokens for that installation are revoked (replay detection)
• Store securely — encrypted at rest, never in client-side code

Refreshing Tokens

{
  "grant_type": "refresh_token",
  "client_id": "sf_app_abc123",
  "client_secret": "your_client_secret",
  "refresh_token": "sf_rt_xxxxx"
}

Token Revocation (on Uninstall)

When a merchant uninstalls your app, all tokens are automatically revoked. Your app will receive an app.uninstalled webhook. You must:

• Delete all stored tokens for this merchant
• Remove any store data you've cached
• Stop any background processing for this store

Session API

Verify a token and check current session info:

Authorization: Bearer sf_at_xxxxx

Response:
{
  "store_id": "merchant_store_uuid",
  "app_id": "your_app_uuid",
  "scopes": ["read_products", "read_orders"],
  "expires_at": "2026-04-22T14:30:00Z"
}

Security Best Practices

Error Handling