Arsitektur Dokumentasi

Cara mengautentikasi permintaan ke API publik Tulis.

Kunci API sebagai Bearer token

Semua permintaan di bawah /v1 memerlukan kunci API yang dikirim sebagai Bearer token:

Tidak ada skema auth lain untuk API publik. Setiap panggilan harus menyertakan header ini.

Konteks workspace bersifat wajib

Setiap permintaan juga harus mengidentifikasi workspace (tenant) mana yang menjadi target. Anda menyediakannya melalui salah satu dari dua metode:

1. Header (direkomendasikan untuk server-to-server):

   X-Workspace-ID: <uuid>

2. Subdomain:

   https://<workspace-slug>.YOUR_HOST/...

Jika Anda tidak memberikan salah satunya, API merespons dengan:

Anda hanya perlu salah satu dari keduanya — tidak perlu keduanya. Header bersifat eksplisit dan berfungsi terlepas dari DNS; pendekatan subdomain berguna ketika setiap workspace sudah memiliki domainnya sendiri.

Mendapatkan kunci API

Hasilkan kunci API dari admin Tulis:

• Buka layar API Keys di dashboard admin.
• Buat kunci baru. Ini memanggil endpoint admin POST /api/api-keys.
• Respons mengembalikan kunci mentah tepat satu kali — salin segera dan simpan dengan aman (misalnya di pengelola rahasia). Anda tidak bisa mengambilnya lagi; jika hilang, rotasi dan buat yang baru.

Kuncinya adalah Bearer token: gunakan langsung sebagai nilai dari header Authorization: Bearer. Perlakukan seperti kata sandi — jangan pernah commit ke version control.

Contoh curl yang benar dan lengkap

curl "https://YOUR_HOST/v1/posts" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID"

Atau, menggunakan subdomain sebagai pengganti header:

curl "https://YOUR_WORKSPACE_SLUG.YOUR_HOST/v1/posts" \
  -H "Authorization: Bearer ***"