Autentikasi API dan quickstart

Dureach menyediakan resource API pelanggan melalui route berversi /api/. Aplikasi juga memiliki route internal /api/v1/ dan /api/v2/. Route internal tidak otomatis menjadi bagian dari API publik; gunakan hanya path yang tercantum dalam referensi API.

Membuat key

1. Buka Settings → Integrations di aplikasi.
2. Buka area OAuth service account dan buat key dengan akses minimum yang diperlukan.
3. Beri nama yang jelas, pilih hanya scope yang diperlukan integrasi, salin sekali ke secret manager di server, dan gunakan YOUR_OAUTH_ACCESS_TOKEN dalam dokumentasi serta contoh.
4. Jika key terekspos, revoke key tersebut dan buat pengganti; jangan pernah menempelkannya di browser bundle, URL, screenshot, issue, atau log.

Autentikasi

Kirim key pada header Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. Jauhkan key dari browser bundle, URL, screenshot, issue, dan log. Request menggunakan workspace aktif yang membuat key tersebut.

curl --fail-with-body 'https://app.dureach.com/api/v2/webhooks?limit=25' \\
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \\
  -H 'Accept: application/json'

Resource pengelolaan OAuth service account dan webhook tersedia di /oauth/service-accounts, /api/v2/webhooks, dan /api/v2/webhook-events. Periksa akses dan entitlement workspace sebelum membangun integrasi.

Bentuk request dan response

Buat key dengan body JSON yang berisi name dan array scopes yang tidak kosong. Response pembuatan berisi id, name, scopes, key, workspace_id, timestamp_created, dan timestamp_updated. key lengkap hanya dikembalikan sekali; pembacaan berikutnya hanya menampilkan prefix yang aman.

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read"]
}

Response list menggunakan array items dan dapat memiliki next_starting_after. Pertahankan cursor persis saat meminta halaman berikutnya. Endpoint list OAuth service account dan webhook default ke 25 record; halaman webhook dan webhook-event dibatasi 100 record. Record webhook berisi campaign, name, target_hook_url, event_type, dan custom_interest_value; record event webhook berisi status delivery dan field retry.

Checklist operasional

1. Gunakan method dan path yang terdokumentasi persis; route privat aplikasi dan runner bukan endpoint API pelanggan.
2. Batasi ukuran halaman dan ikuti field cursor atau pagination dari endpoint.
3. Perlakukan 401 sebagai autentikasi tidak valid atau dicabut, dan 403 sebagai kegagalan izin atau entitlement.
4. Retry hanya kegagalan server sementara, dengan backoff terbatas dan strategi idempotensi untuk write. Jangan membabi buta mengulangi respons 400, 401, 403, 404, 409, atau 429.
5. Simpan request ID dan kode error yang disamarkan untuk dukungan, bukan key atau payload privat.

Buat consumer webhook idempotent: simpan event identifier sebelum melakukan acknowledge, validasi signature jika dikonfigurasi, dan tangani retry delivery.

Error

Error OAuth service account menggunakan JSON dengan statusCode, error, dan message; endpoint baru dapat menambahkan code yang dapat dibaca mesin. Perlakukan 400 sebagai input tidak valid, 401 sebagai kegagalan autentikasi, 403 sebagai kegagalan authorization atau entitlement, 404 sebagai resource tidak dikenal, dan 429 sebagai rate atau usage limit. Jangan membabi buta mengulangi respons 4xx.

Halaman terkait

Lihat API webhooks dan batas penggunaan.

Tabel kegagalan autentikasi

Verifikasi aman

Jalankan request read-only terlebih dahulu, pastikan workspace pada response dan bentuk items, lalu simpan cursor next_starting_after persis seperti yang dikembalikan. Untuk write, catat hanya status HTTP, kode error yang disamarkan, dan request ID. Jangan pernah mencatat bearer key atau payload webhook.