> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Autentikasi API: Amankan Permintaan API KYC

> Autentikasi permintaan API Didit dengan kunci di header x-api-key. Kunci salah/kedaluwarsa menghasilkan 401, tanpa kunci menghasilkan 403.



Prompt Autentikasi API
        Salin prompt ke papan klip



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

Tempel ke

## Menemukan Kunci API AndaDi Didit, kunci API dibatasi pada **Aplikasi** tertentu di dalam akun Anda. Aplikasi adalah ruang kerja tempat Anda dapat mengonfigurasi alur kerja dan mengelola verifikasi untuk proyek atau lingkungan tertentu.Setiap Aplikasi mendapatkan kunci API utama dengan akses penuh saat Anda membuatnya. Anda dapat menambahkan kunci lainnya, masing-masing hanya dengan akses yang dibutuhkan oleh layanan atau mitra. Untuk menemukan kunci Anda:**1. Masuk ke Business Console**Buka [**Didit Business Console**](https://business.didit.me) dan masuk.**2. Pilih Aplikasi Anda**Pilih **Aplikasi** yang ingin Anda gunakan dari menu dropdown di bagian atas.**3. Buka Kunci API**Navigasikan ke **Developers -> API keys** di bilah sisi kiri.**4. Salin atau buat kunci**Kunci **Utama** adalah rahasia milik Aplikasi itu sendiri. Buat kunci baru untuk memberi layanan atau mitra rahasianya sendiri, dengan akses yang diperlukannya.> [!WARNING]
>
> **Kunci API Anda adalah Rahasia — perlakukan seperti kata sandi.**
>
> Kunci utama menyediakan akses penuh ke API atas nama Aplikasi Anda. Jangan pernah mengeksposnya dalam kode frontend, repositori publik, atau bundel sisi klien. Selalu simpan hanya di sisi server.### Format kunci APIKunci API baru dimulai dengan `sk_live_` untuk aplikasi produksi atau `sk_test_` untuk aplikasi sandbox, diikuti oleh 43 karakter yang aman untuk URL (huruf, angka, `-`, dan `_`).
Kunci yang dibuat sebelum format ini tidak memiliki awalan dan tetap berfungsi tanpa perubahan.
Kirimkan seluruh kunci, termasuk awalannya, dalam header `x-api-key`, dan jangan menolak kunci hanya karena tidak memiliki awalan.## Menemukan ID organisasi Anda**ID organisasi** Anda adalah UUID yang mengidentifikasi organisasi Anda. Anda menggunakannya di jalur API dengan cakupan organisasi seperti `/auth/v2/organizations/me/{org_id}/applications/`. Anda dapat menyalinnya langsung dari Business Console, tanpa memerlukan panggilan API:**1. Buka pengaturan organisasi**Di [**Didit Business Console**](https://business.didit.me), buka **Pengaturan Organisasi**.**2. Salin ID organisasi**Kolom **ID organisasi** menampilkan UUID organisasi Anda di sebelah nama organisasi, dilengkapi tombol salin ke papan klip.***## Membuat Permintaan TerautentikasiUntuk mengautentikasi permintaan API, sertakan kunci API rahasia Anda di header HTTP `x-api-key`.Berikut adalah contoh permintaan terautentikasi ke endpoint `Create Session`:```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## Penanganan KesalahanJika kunci API Anda salah, formatnya keliru, atau telah dicabut, API akan mengembalikan `401 Unauthorized`:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Kunci yang kedaluwarsa juga mengembalikan `401`, dengan `"detail": "This API key has expired."`.
Permintaan tanpa kunci mengembalikan `403` dengan `"detail": "You do not have permission to perform this action."`.| Kode Status | Arti |
| - | - |
| **401** | Kunci API salah, format keliru, dicabut, atau kedaluwarsa |
| **403** | Tidak ada kunci API yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan yang diminta, atau permintaan berasal dari alamat di luar daftar IP kunci |
| **403** dengan `"code": "application_deleted"` | Kunci tersebut milik aplikasi yang telah dihapus. API merespons ini selama beberapa menit setelah penghapusan, kemudian menolak kunci seperti kunci tidak valid lainnya. Jangan coba lagi: aplikasi beserta kuncinya sudah tidak ada. |
| **404** | Pada rute sesi: sesi berada di luar alur kerja atau status milik kunci tersebut |Halaman [Kesalahan API](https://docs.didit.me/id/integration/api-errors.md) mencantumkan setiap status, isi respons, dan kode.***## Kunci API dengan cakupan khususBerikan kunci masing-masing untuk setiap layanan atau mitra daripada membagikan kunci utama.
Setiap kunci memiliki aksesnya sendiri: tidak ada, baca, atau tulis untuk setiap sumber daya (sesi, keputusan, media, orang, perusahaan, transaksi, alur kerja, webhook, pengaturan aplikasi, analitik), serta batasan opsional pada beberapa alur kerja, hanya pada sesi yang disetujui, pada daftar alamat IP, dan hingga tanggal kedaluwarsa.
Anda dapat merotasi kunci dengan masa tumpang tindih 24 jam, dan mencabutnya sekaligus.Kunci yang dibuat sebelum adanya akses dengan cakupan khusus tetap mempertahankan akses penuh.Lihat [Kunci API](https://docs.didit.me/id/console/api-keys.md) untuk prasetel, sumber daya yang dicakup oleh masing-masing prasetel, dan bagaimana API merespons kunci dengan cakupan khusus.> [!TIP]
>
> Jika Anda menerima kesalahan `401`, periksa kembali apakah Anda menggunakan kunci API yang benar untuk Aplikasi yang tepat dan pastikan kunci tersebut belum dibuat ulang.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.