Authorization with OAuth

​

Overview

• the merchant-facing authorization step starts on the Scalev frontend authorize page
• the token, introspection, revocation, and installation endpoints live on the /v3/oauth/* API surface

1. Register your application with Scalev
2. Generate PKCE parameters
3. Redirect the merchant’s browser to Scalev’s authorize page
4. The merchant signs in and approves your app
5. Your backend receives an authorization code
6. Your backend exchanges the code for tokens
7. Your backend uses the access token to call Scalev /v3 APIs
8. Your backend refreshes, introspects, or revokes tokens as needed

The authorize page is a frontend route, not a machine API endpoint. It is intentionally separate from the /v3 API contract.

​

URLs

​

Frontend Authorization URL

https://app.scalev.com/oauth/authorize

​

API Base URL

https://api.scalev.com

https://api.scalev.com/v3/oauth/*

​

Step 0: Register and Prepare Your App

• client_id
• client_secret
• redirect_uri
• optional manage_url
• requested scopes
• optional webhook settings
• optional billing tags
• optional IP allowlist

• redirect_uri must match exactly
• client_secret must stay server-side
• if your app uses webhook events, configure the app webhook settings correctly
• if your app supports merchant launch links from Scalev, set manage_url
• merchant installation is blocked until the app is verified

​

Step 1: Generate PKCE Parameters

• a code_verifier
• a code_challenge derived from that verifier using SHA-256 and Base64 URL encoding

​

Code Verifier Example (JavaScript)

function generateCodeVerifier(length = 100) {
  if (!Number.isInteger(length) || length < 43 || length > 128) {
    throw new Error("Length must be an integer between 43 and 128.");
  }

  const charset =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
  const randomValues = crypto.getRandomValues(new Uint8Array(length));

  return Array.from(
    randomValues,
    (byte) => charset[byte % charset.length],
  ).join("");
}

​

Code Challenge Example (JavaScript)

function base64UrlEncode(buffer) {
  return btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

async function generateCodeChallenge(codeVerifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(codeVerifier);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return base64UrlEncode(digest);
}

​

Step 2: Redirect the Merchant to Scalev

https://app.scalev.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=RANDOM_STATE_STRING&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

• PKCE is required
• only S256 is accepted
• the authorize entrypoint is the frontend URL, not the /v3 API
• if the merchant is not signed in, Scalev will take them through login and then return them to the authorize page with the same OAuth query parameters

​

Optional: Fetch Public App Metadata Before Redirect

GET https://api.scalev.com/v3/oauth/application?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

• client_id
• name
• description
• logo_url
• homepage_url
• redirect_uri

​

Step 3: Merchant Reviews and Approves the App

• the app identity
• the requested scopes
• webhook permissions, if applicable
• billing-tag approvals, if applicable

​

Step 4: Receive the Authorization Code

https://your-app.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING

1. verify the returned state
2. exchange the code promptly

• authorization-code flow only
• code TTL is 10 minutes
• each code can be exchanged only once

​

Step 5: Exchange the Code for Tokens

POST https://api.scalev.com/v3/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "code_verifier": "CODE_VERIFIER",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

​

Step 6: Use the Access Token

Authorization: Bearer ACCESS_TOKEN

​

Useful First Checks

​

Token Introspection

POST https://api.scalev.com/v3/oauth/introspect
Content-Type: application/json

{
  "token": "ACCESS_TOKEN",
  "token_type": "access",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

​

Installation Status Snapshot

POST https://api.scalev.com/v3/oauth/installation/status
Content-Type: application/json

{
  "token": "ACCESS_TOKEN",
  "token_type": "access",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

• authorized_business_id
• client_id
• is_active
• is_enabled
• granted_scopes
• webhook_status
• granted_webhook_events
• approved_billing_tags
• manage_launch_available
• updated_at

{
  "authorized_business_id": 123,
  "client_id": "client_abc",
  "is_active": true,
  "is_enabled": true,
  "granted_scopes": ["order:list", "order:read"],
  "webhook_status": "active",
  "granted_webhook_events": ["payment.received", "shipment.status.updated"],
  "approved_billing_tags": [],
  "manage_launch_available": true,
  "updated_at": "2026-04-01T06:10:12.345678Z"
}

​

Step 7: Refresh Access Tokens

POST https://api.scalev.com/v3/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "REFRESH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

{
  "access_token": "NEW_ACCESS_TOKEN",
  "refresh_token": "NEW_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

• always replace both the access token and the refresh token after a successful refresh
• refresh-token exchange is part of the /v3/oauth/token flow
• if the installation is disabled or revoked, refresh may fail

​

Token Lifecycle

• access token TTL: 1 hour
• refresh token TTL: 30 days

​

Token Revocation

POST https://api.scalev.com/v3/oauth/revoke
Content-Type: application/json

{
  "token": "TOKEN_TO_REVOKE",
  "token_type": "refresh",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

• access
• refresh

• HTTP 204 No Content

​

Optional: Merchant Manage Launch Flow

POST https://api.scalev.com/v3/oauth/installation/launch-token/exchange
Content-Type: application/json

{
  "launch_token": "LAUNCH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

• the launch_token is one-time and short-lived
• it is not an access token
• there is no shared manage-link secret; your backend authenticates the exchange with client_id and client_secret

​

Best Practices

1. Redirect merchants to the frontend authorize page, not to a backend /v2 API endpoint.
2. Generate a new PKCE verifier and challenge for every install attempt.
3. Validate state on every callback.
4. Keep client_secret, access tokens, and refresh tokens on the server only.
5. Use only the scopes, webhook events, and billing tags your app actually needs.
6. Treat redirect_uri as an exact-match value.
7. Use /v3/oauth/installation/status when you need the authoritative merchant install snapshot.
8. Use /v3/oauth/introspect for runtime token diagnostics.
9. Handle disabled installations separately from revoked installations.

​

Error Handling

{
  "error": "Error message",
  "error_code": "invalid_grant"
}

• invalid_grant when the code verifier does not match
• invalid_request when required PKCE parameters are missing or malformed