Otorisasi dengan OAuth - Scalev Documentation

Ringkasan

Scalev menggunakan OAuth 2.0 Authorization Code dengan PKCE. Alur ini terbagi ke dua permukaan:

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

Dalam praktiknya, alurnya seperti ini:

Daftarkan aplikasi Anda ke Scalev
Buat parameter PKCE
Redirect browser merchant ke halaman authorize Scalev
Merchant masuk dan menyetujui aplikasi Anda untuk satu atau beberapa bisnis
Backend Anda menerima authorization code
Backend Anda menukar code tersebut dengan token
Backend Anda menggunakan access token untuk memanggil API Scalev /v3, dengan memilih satu bisnis untuk setiap request bisnis jika diperlukan
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

Semua endpoint OAuth publik untuk mesin dalam panduan ini berada di bawah:

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

Langkah 0: Daftarkan dan Siapkan Aplikasi Anda

Sebelum merchant dapat menginstal aplikasi Anda, buat dan konfigurasi aplikasi OAuth Anda di Scalev. Field aplikasi penting meliputi:

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

Aturan penting:

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

Sebelum me-redirect merchant, buat:

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);
}

Simpan code_verifier dengan aman. Anda akan membutuhkannya saat pertukaran token.

Langkah 2: Redirect Merchant ke Scalev

Redirect browser merchant ke:

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

Parameter query wajib:

Parameter	Wajib	Deskripsi
`client_id`	Ya	Client ID aplikasi OAuth Anda
`redirect_uri`	Ya	Harus sama persis dengan redirect URI yang dikonfigurasi
`response_type`	Ya	Harus `code`
`state`	Ya	Nilai acak perlindungan CSRF yang dibuat oleh aplikasi Anda
`code_challenge`	Ya	Hash SHA-256 dari code verifier yang di-encode dengan Base64 URL
`code_challenge_method`	Ya	Harus `S256`

Perilaku saat ini:

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

Jika Anda ingin melakukan preflight atau menampilkan metadata aplikasi dari backend, panggil:

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

Ini mengembalikan metadata aplikasi publik seperti:

client_id
name
description
logo_url
homepage_url
redirect_uri

Langkah 3: Merchant Meninjau dan Menyetujui Aplikasi

Di halaman authorize Scalev, merchant dapat meninjau dan menyetujui:

identitas aplikasi
bisnis yang ingin dihubungkan
scope yang diminta
izin webhook, jika berlaku
persetujuan tag billing, jika berlaku

Merchant dapat memilih beberapa bisnis dalam satu persetujuan OAuth jika keanggotaan mereka di setiap bisnis mengizinkan otorisasi aplikasi. Scalev mencatat akses secara terpisah untuk setiap bisnis yang dipilih. Scope, pengaturan webhook, dan persetujuan tag billing yang sama berlaku untuk semua bisnis yang dipilih pada alur saat ini. Frontend kemudian menyelesaikan alur consent dan me-redirect merchant kembali ke redirect_uri yang Anda konfigurasi.

Langkah 4: Terima Authorization Code

Setelah disetujui, callback backend Anda menerima:

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

Validasi wajib:

verifikasi state yang dikembalikan
segera tukarkan code tersebut

Perilaku authorization code saat ini:

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

Langkah 5: Tukarkan Code dengan Token

Dari backend Anda, tukarkan code di:

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

Respons sukses:

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

Field respons:

Field	Deskripsi
`access_token`	Token yang digunakan untuk permintaan API `/v3` terautentikasi
`refresh_token`	Token yang digunakan untuk memperoleh access token baru
`token_type`	Selalu `Bearer`
`expires_in`	Masa berlaku access token dalam detik

Langkah 6: Gunakan Access Token

Gunakan access token di header Authorization:

Authorization: Bearer ACCESS_TOKEN

Backend Anda kemudian dapat memanggil endpoint /v3 yang diotorisasi merchant dan sesuai dengan scope yang diberikan.

Identitas Token dan Bisnis yang Terhubung

Panggil /v3/me setelah menerima access token:

GET https://api.scalev.com/v3/me
Authorization: Bearer ACCESS_TOKEN

Untuk token OAuth, endpoint ini mengembalikan identitas token dan user serta daftar bisnis aktif yang terhubung ke token:

{
  "auth_method": "oauth",
  "user": {
    "id": 123,
    "unique_id": "USER123",
    "email": "user@example.com",
    "fullname": "Jane Doe",
    "avatar": "https://..."
  },
  "oauth_application": {
    "client_id": "client_abc",
    "name": "Example App"
  },
  "connected_businesses": [
    {
      "unique_id": "ABC123",
      "username": "store-a",
      "name": "Store A",
      "is_enabled": true,
      "scopes": ["order:list", "order:read"]
    }
  ]
}

/v3/me adalah identitas token dan user. Endpoint ini bukan identitas bisnis yang sedang dipilih. Instalasi OAuth yang dicabut atau inactive tidak ditampilkan di connected_businesses[]. Jika tidak ada bisnis aktif yang tersisa, Scalev mengembalikan 403 tanpa data identitas.

Pilih Bisnis untuk Request API

Request API /v3 yang bersifat business-scoped selalu berjalan pada satu bisnis yang dipilih.

jika token memiliki satu bisnis terhubung, selector dapat dihilangkan
jika token memiliki beberapa bisnis terhubung, kirim b_uid=<business.unique_id> pada setiap request business-scoped
gunakan unique_id dari /v3/me.connected_businesses[]
jika akses ke bisnis yang dipilih dicabut atau dinonaktifkan, bisnis tersebut mengembalikan 403 tetapi bisnis aktif lain yang terhubung tetap dapat digunakan

Contoh:

GET https://api.scalev.com/v3/orders?b_uid=ABC123
Authorization: Bearer ACCESS_TOKEN

Gunakan unique_id bisnis yang dikembalikan oleh /v3/me sebagai selector API, misalnya b_uid=ABC123.

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

Gunakan ini untuk memeriksa apakah token saat ini aktif untuk penggunaan runtime.

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

Ini mengembalikan snapshot instalasi merchant, termasuk:

authorized_business_id
client_id
is_active
is_enabled
granted_scopes
webhook_status
granted_webhook_events
approved_billing_tags
manage_launch_available
updated_at

Contoh:

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

/v3/oauth/installation/status mengembalikan satu snapshot koneksi merchant. Jika Anda mengirim referensi token multi-bisnis, Scalev mengembalikan error karena endpoint ini tidak memiliki selector bisnis. Gunakan /v3/me untuk melihat daftar bisnis yang terhubung ke token multi-bisnis.

Langkah 7: Refresh Access Token

Ketika access token kedaluwarsa, gunakan refresh 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"
}

Respons sukses:

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

Catatan penting:

selalu ganti access token dan refresh token setelah refresh berhasil
pertukaran refresh-token adalah bagian dari alur /v3/oauth/token
refresh memuat ulang bisnis yang terhubung ke token dan hanya mempertahankan akses bisnis yang aktif dan enabled
jika satu bisnis dicabut atau dinonaktifkan, token baru hasil refresh hanya berisi bisnis yang masih tersisa
jika bisnis terakhir yang terhubung dicabut atau dinonaktifkan, refresh gagal
access token lama tidak ditulis ulang; sampai token tersebut di-refresh atau kedaluwarsa, request untuk bisnis yang dicabut atau dinonaktifkan akan gagal, tetapi bisnis lain yang terhubung masih dapat berjalan

Siklus Hidup Token

Perilaku saat ini:

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

Revocation Token

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

Nilai token_type saat ini adalah:

access
refresh

Revocation yang berhasil mengembalikan:

HTTP 204 No Content

Opsional: Alur Merchant Manage Launch

Jika aplikasi Anda mendefinisikan manage_url, Scalev dapat meluncurkan merchant ke aplikasi Anda dengan launch_token yang berumur singkat. Tukarkan token tersebut dari backend Anda dengan:

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

Ini mengembalikan bentuk snapshot instalasi yang sama dengan /v3/oauth/installation/status. Catatan penting:

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

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

Rate Limiting

OAuth access token menggunakan rate limit yang di-scope ke aplikasi OAuth dan bisnis yang terhubung. Default saat ini:

10.000 permintaan per jam per bisnis terhubung
100 permintaan per 10 detik per bisnis terhubung untuk burst pendek

Respons rate-limit mengembalikan 429 Too Many Requests dengan header X-Ratelimit-Limit, X-Ratelimit-Remaining, dan X-Ratelimit-Reset. Beberapa limit khusus endpoint lebih ketat, dan respons rate-limit dapat berupa plain text, bukan bentuk error JSON normal.

Penanganan Error

Endpoint OAuth dapat mengembalikan error seperti:

Kode Error	Deskripsi
`invalid_request`	Parameter permintaan hilang atau formatnya salah
`invalid_client`	Autentikasi client gagal
`invalid_grant`	Authorization code, refresh token, atau PKCE verifier tidak valid atau kedaluwarsa
`unauthorized_client`	Client tidak diizinkan menggunakan grant type yang diminta
`server_error`	Kegagalan sisi server yang tidak terduga

Bentuk respons error umum:

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

Kegagalan terkait PKCE biasanya muncul sebagai:

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

​Ringkasan

​URL

​URL Otorisasi Frontend

​Base URL API

​Langkah 0: Daftarkan dan Siapkan Aplikasi Anda

​Langkah 1: Buat Parameter PKCE

​Contoh Code Verifier (JavaScript)

​Contoh Code Challenge (JavaScript)

​Langkah 2: Redirect Merchant ke Scalev

​Opsional: Ambil Metadata Aplikasi Publik Sebelum Redirect

​Langkah 3: Merchant Meninjau dan Menyetujui Aplikasi

​Langkah 4: Terima Authorization Code

​Langkah 5: Tukarkan Code dengan Token

​Langkah 6: Gunakan Access Token

​Identitas Token dan Bisnis yang Terhubung

​Pilih Bisnis untuk Request API

​Pemeriksaan Awal yang Berguna

​Token Introspection

​Snapshot Status Instalasi

​Langkah 7: Refresh Access Token

​Siklus Hidup Token

​Revocation Token

​Opsional: Alur Merchant Manage Launch

​Praktik Terbaik

​Rate Limiting

​Penanganan Error