> ## 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.

# Atur Autentikasi Didit lewat API

> Aktifkan metode masuk, pengaturan, branding, dan proteksi dari kode Anda sendiri dengan grant yang disetujui pemilik atau kunci API dengan cakupan autentikasi.

Didit Authentication memungkinkan Anda mengaktifkan metode login dan membaca kembali pengaturan aplikasi Anda melalui API. Gunakan izin yang disetujui pemilik atau kunci API bernama dengan cakupan `authentication`.

> [!WARNING]
>
> Authentication adalah fitur baru. Atur metode terlebih dahulu di aplikasi sandbox, lalu di aplikasi produksi Anda.

Setiap panggilan di bawah ini ditujukan ke API manajemen Authentication untuk aplikasi Anda. `MANAGEMENT_BASE` adalah:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

Rute yang sama dijelaskan dalam `openapi-authentication.json` di bawah tag `Setup`, yang menjadi sumber pembuatan ulang SDK server.

## Kredensial mana yang digunakan

Salah satu dari tiga kredensial dapat digunakan, dan masing-masing hanya dibatasi pada apa yang telah disetujui pemiliknya.

| Kredensial | Dikirim sebagai | Yang dapat dilakukan |
| - | - | - |
| Kunci API bernama dengan cakupan `authentication` | `x-api-key: <key>` | Mengonfigurasi aplikasinya sendiri, dan membacanya. Kunci dengan `read` hanya dapat membaca pengaturan; `write` dapat membaca dan mengubahnya. |
| Grant yang disetujui pemilik dengan `didit:management` | `Authorization: Bearer <access_token>` | Mengonfigurasi aplikasi dari organisasi yang disetujui saat persetujuan, dalam batas peran orang tersebut. |
| Sesi konsol | `Authorization: Bearer <console session token>` | Membaca atau mengubah pengaturan sesuai keanggotaan organisasi dan peran orang tersebut. Tampilan pengguna akhir juga memerlukan sesi konsol dan izin yang sesuai. |

Kredensial berikut ditolak dengan `403` di setiap rute pengaturan, apa pun yang diminta:

* **Rahasia utama** aplikasi.
* Token dari `POST /programmatic/login`, yang diterbitkan untuk aplikasi, bukan untuk konsol.
* Kunci **tanpa** cakupan `authentication`, termasuk kunci yang dibuat dengan setiap sumber daya pada tingkat tertinggi: kunci tersebut tercantum sebagai akses penuh, membiarkan `scopes` kosong, dan tidak diterima di rute ini.
* Kunci dari **aplikasi lain**, grant yang hanya mencakup `didit:verification`, dan grant yang disetujui untuk organisasi lain.

Permintaan tanpa kredensial sama sekali akan menerima respons `401`. Grant atau kunci tetap memiliki batasannya sendiri: grant dibatasi oleh cakupan, organisasi, dan peran orang tersebut; kunci dibatasi oleh cakupan, daftar izin IP, dan tanggal kedaluwarsanya.

## Setujui akses

### Dengan kunci API bernama

Buka **Developers -> API keys** di [Business Console](https://business.didit.me) dan buat kunci API untuk aplikasi yang sedang Anda siapkan. Berikan resource `authentication` akses **baca** atau **tulis**. Read mencakup setiap panggilan yang membaca pengaturan (`GET`). Write mencakup setiap panggilan yang mengubah pengaturan (`POST`, `PUT`, `PATCH`, `DELETE`) dan juga membaca pengaturan tersebut. Lihat [Kunci API](https://docs.didit.me/id/console/api-keys.md) untuk masa berlaku, daftar IP yang diizinkan, dan rotasi. Satu kunci API hanya milik satu aplikasi dan hanya berfungsi untuk aplikasi itu.

### Melalui koneksi MCP

Agen yang terhubung ke server MCP Didit menggunakan izin yang disetujui pemiliknya di layar persetujuan, dengan `didit:management`. Lihat [Autentikasi MCP](https://docs.didit.me/id/integration/mcp/authentication.md#masuk-dengan-didit).

### Untuk pemilik tanpa kata sandi

Pemberian kode perangkat ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) memungkinkan pemilik yang masuk dengan Google, kunci sandi, atau kode yang dikirim lewat email untuk menyetujui akses yang sama dari browser mana pun, tanpa mengetikkan kata sandi. Lihat [masuk tanpa browser](https://docs.didit.me/id/integration/mcp/authentication.md#masuk-tanpa-browser-kode-perangkat).

## Aktifkan kode email

`PUT methods/{name}/` menerima `enabled`, dan tidak ada parameter lain untuk metode yang tidak memerlukan kredensial.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

Respons berisi metode sebagaimana kondisinya saat ini:

```json theme={null}
{"name": "code", "enabled": true}
```

Saat Anda membaca kembali konfigurasi, entri untuk kode email menyertakan `credential_source: null`. Metode yang selalu aktif tidak dapat dinonaktifkan: permintaan tersebut merespons dengan `{"enabled": "always_on"}`.

## Mengaktifkan Google

Metode sosial menggunakan kredensial aplikasi OAuth Anda sendiri, atau aplikasi uji Didit pada aplikasi sandbox.

### Dengan aplikasi Google Anda sendiri

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Daftarkan `callback_uri` yang dikembalikan oleh respons tersebut di penyedia Anda. Rahasia hanya dapat ditulis: tidak ada respons yang mengembalikannya, dan `client_id` adalah satu-satunya bagian yang bisa dibaca kembali. Mengaktifkan metode tanpa kredensial, jika sebelumnya belum ada kredensial yang tersimpan, akan menghasilkan `{"credentials": "required"}`.

### Dengan aplikasi uji Didit (`didit_test`)

Aplikasi **sandbox** dapat menggunakan aplikasi sosial milik Didit sebagai pengganti aplikasi Anda sendiri, yang cukup untuk menyelesaikan pengaturan dan membuktikan bahwa pengaturan itu berfungsi:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` mencakup **Google, Microsoft, Apple dan GitHub**, hanya pada aplikasi sandbox.

| Respons | Kapan |
| - | - |
| `{"credential_source": "sandbox_only"}` | Aplikasi berada di lingkungan produksi. Aplikasi uji tidak pernah melayani proses masuk di lingkungan produksi. |
| `{"credential_source": "unavailable"}` | Penerapan tidak memiliki aplikasi uji untuk penyedia tersebut, sehingga metode tetap nonaktif. |
| `200` dengan `configured: true` | Aplikasi uji melayani metode tersebut, dan proses masuk yang di-hosting menawarkannya. |

`GET` pada konfigurasi menyebutkan penyedia yang dapat dilayani aplikasi uji untuk aplikasi ini dalam `didit_test_credentials`. Nilainya `false` untuk keempat penyedia pada aplikasi produksi.

## Membaca ulang pengaturan

`GET` pada `MANAGEMENT_BASE` adalah pembacaan ulang: setiap metode dengan `enabled` dan `credential_source`, beserta URL callback, aturan sesi, dan kebijakan pendaftaran.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Metode yang dinonaktifkan juga ditampilkan, sehingga satu `GET` sudah menunjukkan mana yang aktif dan mana yang tidak. `enabled` di bagian atas bernilai `false` jika Autentikasi dinonaktifkan untuk aplikasi. Setiap perubahan pengaturan yang dilakukan dengan izin manajemen atau kunci API bernama akan mengembalikan `409` dengan `{"detail": "product_disabled"}`, dan tidak ada yang disimpan. Tidak ada panggilan pengaturan yang mengaktifkan Autentikasi: seseorang mengaktifkannya untuk aplikasi di konsol, dan panggilan Anda berfungsi sejak saat itu.

## Sisa penyiapan

| Rute, di bawah `MANAGEMENT_BASE` | Metode | Isinya |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Akses agen, organisasi, kebijakan MFA, peran anggota default, event webhook yang dinonaktifkan |
| `onboarding/` | `GET`, `PATCH` | Langkah pengaturan yang sudah selesai, dan apakah pengguna masuk melalui halaman yang di-hosting atau layar Anda sendiri |
| `branding/` | `GET`, `PATCH` | Teks halaman yang di-hosting dan tautan hukum (logo dan warna berasal dari Kustomisasi) |
| `protection/` | `GET`, `PATCH` | Kebijakan perlindungan bot ([perlindungan bot](https://docs.didit.me/id/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | Tingkat verifikasi pendaftaran, aturan step-up, dan klaim token |
| `emails/`, `emails/{key}/` | `GET` | Email untuk masuk yang dikirim aplikasi ini, dan pratinjau yang sudah dirender |
| `domain/` | `GET`, `PUT`, `DELETE` | Origin yang di-hosting dan domain kustom untuk masuk |
| `domain/verify/`, `domain/activate/` | `POST` | Memeriksa DNS dan sertifikat domain, lalu menjadikannya origin kanonis |
| `native-apps/` | `GET`, `PUT` | Aplikasi iOS dan Android yang berbagi passkey aplikasi |

Izin akses atau kunci hanya mendapatkan pengaturan dan penghitungnya, tidak pernah data pengguna akhir: `users/`, `sessions/`, `sign-ins/`, `overview/`, organisasi pelanggan, peran, impor, sesi agen, dan email uji tetap memerlukan sesi konsol.

Pengaturan `agent_humans_only` berlaku untuk seluruh aplikasi. Hanya pemilik atau admin organisasi yang dapat mengubahnya. Kunci bernama menerima `403 owner_or_admin_required`. Mengaktifkan pengaturan ini juga memerlukan passkey yang sudah didaftarkan (`passkey_required`).

## Errors

| Respons | Arti |
| - | - |
| `401` | Tidak ada kredensial. |
| `403` | Kredensial yang tidak dapat mengonfigurasi aplikasi ini, atau salah satu batasnya sendiri: `ip_not_allowed`, kunci yang sudah kedaluwarsa, atau kunci hanya-baca pada rute penulisan. |
| `409 {"detail": "product_disabled"}` | Autentikasi dinonaktifkan untuk aplikasi, sehingga perubahan pengaturan yang dibuat dengan hibah otorisasi atau kunci ditolak. Seseorang mengaktifkannya di konsol. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | Sumber daya yang diminta tidak dapat ditemukan. |


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