OAuth 2.0

Wazapin mendukung OAuth 2.0 untuk integrasi yang membutuhkan akses terdelegasi, bukan API key jangka panjang. Pakai OAuth untuk CLI, aplikasi desktop, atau aplikasi eksternal yang bertindak atas nama pengguna Wazapin.

Untuk integrasi server-to-server yang sepenuhnya kamu kendalikan, API key tetap menjadi pilihan yang lebih sederhana.

OAuth server

Pakai https://api.wazapin.com sebagai issuer:

https://api.wazapin.com

Temukan endpoint dan kemampuan terbaru secara programmatic:

curl -sS https://api.wazapin.com/.well-known/oauth-authorization-server

Discovery document saat ini mendukung:

• Authorization Code dengan PKCE (S256)
• Refresh token
• Device Authorization Grant (RFC 8628)
• Token introspection (RFC 7662)
• Token revocation (RFC 7009)

Daftarin OAuth client

OAuth client harus didaftarkan sebelum dapat meminta authorization. Pendaftaran menyediakan client_id, redirect URI yang diizinkan, grant type, response type, dan scope.

Jangan menaruh client secret di browser, aplikasi desktop, CLI, atau public client lainnya. Public client harus memakai PKCE. Confidential client hanya boleh memakai secret dari server yang terlindungi.

Client wazapin-docs tersedia untuk integrasi dokumentasi hosted. Callback URL-nya bergantung pada deployment; jangan menyalinnya untuk aplikasi baru. Minta Wazapin mendaftarkan client dan callback URL yang tepat sebelum memakai Authorization Code di production.

Device Authorization flow

Pakai Device Authorization untuk CLI, sesi SSH, atau perangkat lain yang tidak dapat menerima callback URL dengan aman. Ini adalah flow yang direkomendasikan untuk integrasi headless.

1. Minta device code

Endpoint device menerima JSON. client_id wajib diisi; scope adalah daftar yang dipisahkan spasi.

curl -sS -X POST "https://api.wazapin.com/v1/oauth/device" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "scope": "messages:read messages:send channels:read"
  }'

Response sukses berisi:

{
  "device_code": "DEVICE_CODE",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://app.wazapin.id/v1/oauth/device",
  "verification_uri_complete": "https://app.wazapin.id/v1/oauth/device?user_code=ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}

URL verifikasi dan masa berlaku dikembalikan oleh server. Selalu pakai nilai dari response, jangan hardcode.

2. Minta pengguna mengotorisasi device

Buka verification_uri_complete di browser. Pengguna login, memilih organisasi Wazapin yang boleh diakses device, lalu mengotorisasi device.

Tampilkan user_code sebagai fallback jika complete URL tidak dapat dibuka.

3. Poll token

Lakukan polling tidak lebih sering dari interval yang dikembalikan. Token endpoint memakai body form-encoded standar OAuth, bukan JSON.

curl -sS -X POST "https://api.wazapin.com/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "device_code=DEVICE_CODE" \
  --data-urlencode "client_id=YOUR_CLIENT_ID"

Sebelum pengguna selesai, server mengembalikan error OAuth seperti:

{
  "error": "authorization_pending"
}

Hentikan polling saat code expired atau error tidak dapat dipulihkan. Setelah disetujui, response berisi bearer token:

{
  "access_token": "wazapin_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "messages:read messages:send channels:read"
}

4. Panggil API

curl -sS "https://api.wazapin.com/v1/channels" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Jika pengguna mengotorisasi lebih dari satu organisasi, kirim identifier organisasi yang diperlukan resource tujuan. Simpan access token di credential store lokal yang aman dan jangan mencetaknya ke log.

Authorization Code + PKCE

Pakai Authorization Code dengan PKCE untuk aplikasi web, desktop, dan mobile yang dapat membuka browser serta menerima redirect.

Authorization endpoint:

GET https://api.wazapin.com/v1/oauth/authorize

Buat code_verifier dengan entropy tinggi, turunkan S256 code_challenge, dan simpan verifier sampai token exchange. Redirect pengguna ke URL seperti ini:

https://api.wazapin.com/v1/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fyour-app.example%2Foauth%2Fcallback&
  scope=messages%3Aread%20messages%3Asend&
  state=RANDOM_STATE&
  code_challenge=BASE64URL_SHA256_CODE_VERIFIER&
  code_challenge_method=S256

Validasi state saat browser kembali ke callback. Setelah itu tukarkan authorization code sekali pakai:

curl -sS -X POST "https://api.wazapin.com/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://your-app.example/oauth/callback" \
  --data-urlencode "code_verifier=ORIGINAL_CODE_VERIFIER"

redirect_uri harus sama persis dengan URI yang didaftarkan untuk client. Domain hosted docs bukan callback OAuth umum; daftarkan client untuk aplikasi kamu sendiri sebelum menguji flow ini.

Refresh access token

Jika refresh token diterbitkan untuk client kamu, tukarkan di token endpoint yang sama:

curl -sS -X POST "https://api.wazapin.com/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "refresh_token=REFRESH_TOKEN"

Perlakukan refresh token sebagai credential. Simpan dengan aman dan rotate atau revoke saat pengguna memutuskan integrasi.

Introspect token

Pakai introspection dari backend tepercaya untuk memeriksa apakah bearer token masih aktif:

curl -sS -X POST "https://api.wazapin.com/v1/oauth/introspect" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "ACCESS_TOKEN"
  }'

Token aktif mengembalikan active: true beserta metadata token. Token yang tidak dikenal atau expired mengembalikan:

{
  "active": false
}

Jangan expose response introspection ke client yang tidak tepercaya.

Revoke token

Revoke access atau refresh token saat pengguna memutuskan integrasi:

curl -sS -X POST "https://api.wazapin.com/v1/oauth/revoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "ACCESS_OR_REFRESH_TOKEN",
    "token_type_hint": "access_token"
  }'

Endpoint ini idempotent untuk token yang sudah direvoke. Hapus token lokal setelah request revoke sukses.

OAuth errors

OAuth error dikembalikan sebagai JSON dari token endpoint. Kasus umum:

Checklist keamanan

• Pakai PKCE dengan S256 untuk public client.
• Validasi state pada setiap authorization callback.
• Pakai redirect URI yang exact dan sudah didaftarkan; jangan menerima callback URL sembarang.
• Minta scope minimum yang dibutuhkan integrasi.
• Jauhkan access dan refresh token dari source control, URL, log, dan analytics client-side.
• Revoke token saat pengguna memutuskan integrasi.

Langkah berikutnya

• Autentikasi API
• Ringkasan API
• Ringkasan CLI
• API Reference