Developer · API

Autentikasi & sesi

Gunakan sesi Better Auth yang sama dengan aplikasi. Cookie, origin, kepemilikan resource, dan format respons auth perlu ditangani dengan benar.

Unduh OpenAPI 3.1

Cookie sesi, bukan Bearer pelanggan

ping! memakai email + password dengan Better Auth. Browser mengirim cookie HttpOnly secara otomatis pada request same-origin. Jangan mengambil token sesi ke JavaScript, menyimpannya di localStorage, atau memakai rahasia provider sebagai identitas pelanggan.

Cookie sesi, bukan Bearer pelanggan
Kebutuhan	Lokasi / perilaku
Client auth	lib/auth-client.ts mengekspor authClient; pakai authClient.signIn, authClient.signUp, authClient.signOut, dan authClient.useSession.
Handler	/api/auth/[...all] meneruskan request ke Better Auth.
Cookie	better-auth.session_token atau __Secure-better-auth.session_token, mengikuti secure base URL/config auth. Biarkan browser/cookie jar memilih.
Sesi	Konfigurasi expiresIn 7 hari, updateAge 1 hari. Gunakan hasil pemeriksaan sesi, jangan menghitung validitas sendiri.
Identitas server	requireUser membaca sesi dan akun terkini. Penangguhan berlaku juga pada sesi yang sudah terbit.

Masuk lewat client yang tersedia

Di dalam handler form client, gunakan email dan password dari input pengguna. Login dan pendaftaran wajib menyertakan token Cloudflare Turnstile dari widget halaman pada header x-captcha-response; token hanya berlaku sekali dan terikat ke action login atau register. Setelah masuk, arahkan ke aplikasi dan muat data akun. Jangan mencetak respons login, cookie, atau password ke log.

Handler login · lib/auth-client.ts

import { authClient } from "@/lib/auth-client";

const result = await authClient.signIn.email({
  email,
  password,
  fetchOptions: { headers: { "x-captcha-response": turnstileToken } },
});
if (result.error) {
  throw new Error(result.error.message ?? "Login gagal");
}

window.location.assign("/dashboard");

Auth punya kontrak sendiri

Jangan memanggil endpoint Better Auth melalui api() dari lib/ping/client.ts. Wrapper itu mengharapkan ok/data; respons auth mengikuti Better Auth, bukan envelope route aplikasi.

cURL dengan cookie jar

Untuk pengujian di terminal pengembanganmu, set PING_ORIGIN ke origin instalasi yang kamu kelola, tanpa slash penutup. Siapkan cookie jar privat. Request login membaca JSON lewat stdin: masukkan objek email dan password akun uji, kemudian akhiri input. Jangan tulis password pada argumen command atau memasukkan cookie jar ke Git. Login juga memerlukan token Turnstile sekali pakai dengan action login di header x-captcha-response; isi PING_TURNSTILE_TOKEN dari widget login instalasimu.

Persiapan sesi · shell lokal

umask 077
export PING_ORIGIN="http://localhost:3000"
export PING_COOKIE_JAR="$(mktemp)"

curl --fail-with-body --request POST \
  --header "Origin: $PING_ORIGIN" \
  --header "Content-Type: application/json" \
  --header "x-captcha-response: $PING_TURNSTILE_TOKEN" \
  --cookie-jar "$PING_COOKIE_JAR" \
  --data-binary @- \
  "$PING_ORIGIN/api/auth/sign-in/email"

Login yang berhasil menyimpan Set-Cookie ke jar. Semua contoh cURL pada referensi memakai jar itu; jangan menganggap HTTP 200 pada request lain membuktikan sesi masih aktif. Hapus jar lokal setelah selesai. Untuk deployment HTTPS, gunakan origin HTTPS sebenarnya, bukan domain dari contoh.

Periksa sesi tanpa mutasi

curl --fail-with-body \
  --cookie "$PING_COOKIE_JAR" \
  "$PING_ORIGIN/api/me"

Origin dan body mutasi

Request POST/PATCH ke API aplikasi harus memakai Content-Type: application/json. Aksi cancel/complete tetap memerlukan body {}.
Browser mengirim Origin. Server memeriksanya terhadap origin request dan origin auth/preview yang dipercaya. Origin yang tidak dipercaya menghasilkan FORBIDDEN.
Jangan memakai mode no-cors, mengganti cookie dengan Bearer, atau membuka wildcard origin untuk mengakali pembatasan. Ini bukan API browser lintas domain.
Identitas tidak dikirim sebagai userId pada body. Server membatasi query berdasarkan sesi, termasuk detail order, ledger, dan pembayaran.

Preview berbeda dari sandbox transaksi

/preview menggunakan transport demo terisolasi dan tidak mengakses API produksi. Untuk membuktikan autentikasi/provider sungguhan, gunakan instalasi uji yang dikonfigurasi. Jangan menghapus proteksi preview.

Saat akses ditolak

Saat akses ditolak
HTTP / kode	Tindakan
401 · UNAUTHENTICATED	Minta login ulang. Periksa cookie pada origin yang sama.
403 · ACCOUNT_SUSPENDED	Hentikan alur dan hubungi pengelola akun.
403 · FORBIDDEN	Periksa origin dan izin. Endpoint admin memerlukan role admin.
404 · NOT_FOUND	Resource tidak ada atau bukan milik sesi. Jangan mencoba ID pengguna lain.