Otorisasi dengan OAuth

​

Ringkasan

• langkah otorisasi yang menghadap merchant dimulai di halaman authorize frontend Scalev
• endpoint token, introspection, revocation, dan installation berada di permukaan API /v3/oauth/*

1. Daftarkan aplikasi Anda ke Scalev
2. Buat parameter PKCE
3. Redirect browser merchant ke halaman authorize Scalev
4. Merchant masuk dan menyetujui aplikasi Anda
5. Backend Anda menerima authorization code
6. Backend Anda menukar code tersebut dengan token
7. Backend Anda menggunakan access token untuk memanggil API Scalev /v3
8. Backend Anda melakukan refresh, introspection, atau revoke token sesuai kebutuhan

Halaman authorize adalah rute frontend, bukan endpoint API untuk mesin. Halaman ini sengaja dipisahkan dari kontrak API /v3.

​

URL

​

URL Otorisasi Frontend

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

​

Base URL API

https://api.scalev.com

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

​

Langkah 0: Daftarkan dan Siapkan Aplikasi Anda

• client_id
• client_secret
• redirect_uri
• manage_url opsional
• scope yang diminta
• pengaturan webhook opsional
• tag billing opsional
• IP allowlist opsional

• redirect_uri harus sama persis
• client_secret harus tetap berada di sisi server
• jika aplikasi Anda menggunakan event webhook, konfigurasi pengaturan webhook aplikasi dengan benar
• jika aplikasi Anda mendukung link launch merchant dari Scalev, atur manage_url
• instalasi merchant diblokir sampai aplikasi terverifikasi

​

Langkah 1: Buat Parameter PKCE

• code_verifier
• code_challenge yang diturunkan dari verifier tersebut menggunakan SHA-256 dan encoding Base64 URL

​

Contoh Code Verifier (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("");
}

​

Contoh Code Challenge (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);
}

​

Langkah 2: Redirect Merchant ke 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 wajib digunakan
• hanya S256 yang diterima
• entrypoint authorize adalah URL frontend, bukan API /v3
• jika merchant belum masuk, Scalev akan membawa mereka melalui login lalu mengembalikannya ke halaman authorize dengan parameter query OAuth yang sama

​

Opsional: Ambil Metadata Aplikasi Publik Sebelum 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

​

Langkah 3: Merchant Meninjau dan Menyetujui Aplikasi

• identitas aplikasi
• scope yang diminta
• izin webhook, jika berlaku
• persetujuan tag billing, jika berlaku

​

Langkah 4: Terima Authorization Code

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

1. verifikasi state yang dikembalikan
2. segera tukarkan code tersebut

• hanya alur authorization-code
• TTL code adalah 10 menit
• setiap code hanya dapat ditukar satu kali

​

Langkah 5: Tukarkan Code dengan Token

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
}

​

Langkah 6: Gunakan Access Token

Authorization: Bearer ACCESS_TOKEN

​

Pemeriksaan Awal yang Berguna

​

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"
}

​

Snapshot Status Instalasi

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"
}

​

Langkah 7: Refresh Access Token

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
}

• selalu ganti access token dan refresh token setelah refresh berhasil
• pertukaran refresh-token adalah bagian dari alur /v3/oauth/token
• jika instalasi dinonaktifkan atau dicabut, refresh dapat gagal

​

Siklus Hidup Token

• TTL access token: 1 jam
• TTL refresh token: 30 hari

​

Revocation Token

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

​

Opsional: Alur Merchant Manage Launch

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"
}

• launch_token bersifat sekali pakai dan berumur singkat
• token ini bukan access token
• tidak ada secret manage-link bersama; backend Anda mengautentikasi pertukaran dengan client_id dan client_secret

​

Praktik Terbaik

1. Redirect merchant ke halaman authorize frontend, bukan ke endpoint API backend /v2.
2. Buat PKCE verifier dan challenge baru untuk setiap percobaan instalasi.
3. Validasi state pada setiap callback.
4. Simpan client_secret, access token, dan refresh token hanya di server.
5. Gunakan hanya scope, event webhook, dan tag billing yang benar-benar dibutuhkan aplikasi Anda.
6. Perlakukan redirect_uri sebagai nilai yang harus sama persis.
7. Gunakan /v3/oauth/installation/status saat Anda membutuhkan snapshot instalasi merchant yang otoritatif.
8. Gunakan /v3/oauth/introspect untuk diagnostik token runtime.
9. Tangani instalasi yang dinonaktifkan secara terpisah dari instalasi yang dicabut.

​

Penanganan Error

{
  "error": "Pesan error",
  "error_code": "invalid_grant"
}

• invalid_grant ketika code verifier tidak cocok
• invalid_request ketika parameter PKCE wajib hilang atau formatnya salah