Auth API

Auth API adalah alur OAuth yang mengautentikasi ServiceUser (pendaftar umum dari produk yang dijalankan oleh sebuah Space) melalui login sosial. Saat pengguna masuk dengan penyedia yang terhubung ke konfigurasi ServiceLogin (misalnya Google), API ini menerbitkan accessToken dan refreshToken. accessToken yang diterbitkan adalah Bearer token yang hanya digunakan untuk memanggil ACMA dan ACDA, serta tidak dapat dipakai pada CMA maupun CDA. Tidak ada token yang melewati batas identitas.

Base URL-nya adalah https://auth.weegloo.com/v1, dan semua path berada di bawah /spaces/{spaceId}/.... Semua badan permintaan dan respons berupa JSON. Untuk aplikasi browser, disarankan menggunakan SDK resmi weegloo-service-user daripada menangani protokol jaringan ini secara langsung. Halaman ini membahas protokol jaringan HTTP yang dipanggil SDK tersebut secara internal. Gunakan sebagai rujukan ketika Anda mengimplementasikan alur ini sendiri di lingkungan yang tidak dapat memakai SDK (server, native, skrip).

Alur login

Alur login di bawah ini mengacu pada aplikasi browser web. Aplikasi native (Android·iOS) menangani callback secara berbeda, sehingga dibahas terpisah di Callback aplikasi native.

Login berlangsung dalam empat langkah.

1. Arahkan browser ke URL masuk login (/spaces/{spaceId}/login/oauth2/{provider}). URL ini memulai rantai pengalihan yang menuju ke layar login penyedia (Google).
2. Setelah login selesai, Weegloo mengembalikan browser ke callbackUrl yang dikonfigurasi pada ServiceLogin, dengan menambahkan ?exchangeToken=<token sekali pakai> pada alamatnya.
3. Halaman callback membaca exchangeToken dari alamat, mengirimnya ke endpoint penukaran token (POST /spaces/{spaceId}/oauth/token), dan menerima accessToken serta refreshToken sebagai respons.
4. Selanjutnya, panggil ACMA dan ACDA menggunakan accessToken sebagai Bearer token. Perbarui dengan refreshToken sebelum kedaluwarsa (expiresAt), dan cabut token saat keluar.

exchangeToken bersifat sekali pakai. Segera setelah memproses callback, hapus token dari bilah alamat untuk mencegah paparan dan penggunaan ulang (jika menggunakan SDK, ini ditangani secara otomatis).

Callback aplikasi native: jembatan deep link

Aplikasi native Android dan iOS juga login dengan alur OAuth yang sama. Namun, karena callbackUrl hanya bisa diisi alamat web, cara menghubungkannya berbeda.

callbackUrl yang didukung secara resmi adalah alamat web seperti https://.... Skema kustom yang didaftarkan aplikasi seperti myapp:// ditolak, sehingga tidak bisa dipakai langsung sebagai alamat callback. Karena itu, aplikasi native menjadikan callbackUrl sebagai halaman jembatan https yang diunggah ke Web Hosting, lalu halaman itu meneruskan ?exchangeToken=... yang dibawa callback ke deep link aplikasi (misalnya myapp://auth/callback?exchangeToken=...). Aplikasi kemudian melakukan sendiri penukaran token (langkah 3 alur login di atas, POST /spaces/{spaceId}/oauth/token) dengan exchangeToken tersebut.

• Yang diteruskan lewat deep link hanya exchangeToken yang sekali pakai. accessToken dan refreshToken ditukar dan diterima langsung oleh aplikasi, jadi tidak melewati deep link. Halaman jembatan pun menghapus exchangeToken dari alamat setelah meneruskan nilainya (prinsip yang sama dengan callback pada alur login).
• Sebisa mungkin gunakan deep link terverifikasi (Android App Links, iOS Universal Links). Skema kustom yang tidak terverifikasi bisa dicegat oleh aplikasi lain yang terpasang di perangkat.
• Klien OAuth dari penyedia (misalnya Google) dibuat dengan tipe Web application meskipun ini aplikasi native. Sebab pengalihan OAuth menuju auth.weegloo.com (alamat web), bukan ke aplikasi.

Cara men-deploy halaman jembatan dibahas di Web Hosting.

Model token

Penukaran dan pembaruan token mengembalikan respons token dengan bentuk yang sama. String token dan waktu yang termuat dalam respons adalah nilai contoh di bawah ini; pada kenyataannya berupa string rahasia yang buram (karena alur ini melewati login penyedia, nilai sebenarnya tidak dapat disalin apa adanya).

{
  "accessToken": "QY3xK9pR2mLs7Vc0Zt8Nf4Wd1Bj6Hg5Ua2Ee9Ck3PoZt8Nf4Wd",
  "tokenType": "Bearer",
  "scope": ["APP"],
  "createdAt": "2026-06-18T05:00:00.000Z",
  "expiresAt": "2026-06-19T05:00:00.000Z",
  "refreshToken": "Rf7Hn2Qw9Zx4Tp1Lk6Vc3Bm8Yd5Gs0Ae2Uj7Co4NeLk6Vc3Bm",
  "refreshExpiresAt": "2026-06-21T05:00:00.000Z"
}

Masa hidup ketiga token adalah sebagai berikut.

• exchangeToken bersifat sekali pakai dan berumur pendek. Token ini harus segera ditukar setelah callback. Token ini tidak termuat dalam respons penukaran, melainkan diteruskan melalui alamat pada langkah 2 alur login.
• Masa hidup accessToken bukan nilai tetap. Waktu kedaluwarsa tepatnya termuat pada expiresAt di respons, jadi gunakan nilai itu untuk menentukannya. Hanya untuk ACMA dan ACDA.
• refreshToken berlaku selama tiga hari setelah diterbitkan (refreshExpiresAt). Saat pembaruan dipanggil, pasangan accessToken dan refreshToken baru diterbitkan dan pasangan sebelumnya dicabut (rotasi, rotation). Setiap kali pembaruan dilakukan, refreshToken sebelumnya tidak dapat lagi digunakan.

API

Base URL keempat endpoint di bawah ini semuanya adalah https://auth.weegloo.com/v1. Dibahas berurutan: masuk login (GET), penukaran token (POST), pembaruan token (POST), dan keluar (DELETE).

Dokumen terkait

• Login ServiceUser (konsep): Cara mengonfigurasi ServiceLogin di studio konten.
• ACMA: API untuk menangani konten anggota dengan token yang diterbitkan.
• ACDA: API baca yang dikirimkan kepada anggota.