> ## 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 MCP Didit: Masuk dengan Didit (OAuth)

> Autentikasi MCP Didit memakai OAuth 2.1 dengan PKCE, registrasi klien dinamis, scope, dan peran, plus cara terhubung dari setiap klien.

Didit MCP melakukan autentikasi dengan **Masuk dengan Didit** (OAuth 2.1). MCP bertindak sebagai **pengguna** Didit dengan izin sesuai peran konsol Anda. **Tidak ada mode kunci API.**

***

## Masuk dengan Didit

Server yang di-hosting (`https://mcp.didit.me/mcp`) adalah **server sumber daya** OAuth 2.1. **Didit Business Console** (`business.didit.me`) adalah **server otorisasi** yang menampilkan layar persetujuan dan menerbitkan token. Klien MCP Anda menjalankan alur standar ini secara otomatis:

**1. Temukan**

Klien mengirim permintaan ke `/mcp` tanpa token dan menerima `401` dengan header `WWW-Authenticate: Bearer` yang `resource_metadata`-nya mengarah ke metadata resource yang dilindungi (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Dokumen tersebut menyebutkan resource (`https://mcp.didit.me/mcp`), authorization server (`https://business.didit.me`), dan scope yang didukung. Dokumen yang sama juga tersedia di root origin, `https://mcp.didit.me/.well-known/oauth-protected-resource`, untuk klien yang memeriksa lokasi tersebut terlebih dahulu.

**2. Daftar (pendaftaran klien dinamis)**

Klien membaca metadata authorization server di `https://business.didit.me/.well-known/oauth-authorization-server` dan, jika belum memiliki ID klien, mendaftarkan dirinya sendiri di `registration_endpoint` (RFC 7591). Anda tidak perlu menyiapkan apa pun terlebih dahulu: klien lokal dengan callback loopback atau native (Claude Code, Cursor, MCP Inspector) dan klien yang di-hosting di cloud dengan callback yang telah ditinjau (Claude) sama-sama mendaftar dengan cara ini. URL callback jarak jauh yang belum ditinjau Didit akan ditolak dengan `invalid_redirect_uri`; klien tersebut memerlukan operator untuk mendaftarkannya terlebih dahulu.

**3. Otorisasi (PKCE)**

Klien membuka `https://business.didit.me/authorize` dengan tantangan PKCE S256. Anda masuk (atau mendaftar) dan melihat secara persis izin apa saja yang diminta. Klien bersifat publik: token endpoint tidak menerima client secret (`token_endpoint_auth_methods_supported` bernilai `none`), sehingga PKCE yang mengikat kode ke klien.

**4. Persetujuan**

Anda menyetujui. Konsol membuat sesi untuk aplikasi tersebut, yang terikat pada scope yang Anda setujui, lalu mengembalikan kode otorisasi. Klien menukarnya di `token_endpoint` dengan token akses dan token refresh.

**5. Panggil tool**

Klien mengirim token akses pada setiap permintaan. MCP memvalidasinya dengan introspeksi token RFC 7662 terhadap layanan autentikasi Didit (token bersifat opak, bukan JWT), membaca izin organisasi Anda dari respons introspeksi, dan bertindak atas nama **Anda** selama permintaan tersebut berlangsung.

### Cakupan akses

Metadata resource mengiklankan tiga scope. Layar persetujuan menampilkan scope yang diminta klien dalam bahasa yang mudah dipahami:

| Scope | Memberikan akses |
| - | - |
| `didit:management` | Kelola ruang kerja Anda: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml`, dan `analytics`. |
| `didit:verification` | Jalankan dan tinjau verifikasi: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist`, dan `analytics`. |
| `didit:staff` | Dicadangkan untuk akun staf Didit. Scope ini tidak membuka apa pun untuk akun biasa, dan build sumber terbuka tidak mendefinisikan tool khusus staf. |

Kedua scope menyertakan `analytics`. Mengelola `lists` memerlukan `didit:management`; mengakses `blocklist` memerlukan `didit:verification`.

[Referensi tool](https://docs.didit.me/id/integration/mcp/tools.md) mencantumkan scope yang berlaku untuk setiap tool. Scope yang Anda setujui dibawa pada token dan ditegakkan di sisi server. Karena itu, aplikasi yang hanya terhubung dengan `didit:verification` akan ditolak pada area manajemen, meskipun peran Anda sendiri mengizinkannya. Authorization server juga mengenal scope OpenID (`openid profile email`); koneksi yang hanya meminta scope tersebut hanya dapat mengetahui siapa Anda, tidak lebih.

Izin efektif aplikasi adalah **irisan** dari scope yang disetujui dan peran konsol Anda, bukan yang lebih luas dari keduanya.

Untuk membuat sesi verifikasi dengan `didit_session_create`, Anda memerlukan scope `didit:verification` **dan** peran dengan `create:sessions` atau `write:sessions`. Peran **Pengembang** menyertakan `create:sessions`. Menyetujui `didit:management` saja tidak mengizinkan pembuatan sesi, meskipun peran Anda memiliki izin yang diperlukan.

### Peran dan izin

Token dari server yang di-hosting merepresentasikan **Anda**, sehingga agen dapat bekerja di **setiap organisasi tempat Anda menjadi anggota** dalam satu koneksi. Tool lintas-aplikasi (`didit_session_search`, `didit_analytics`, `didit_context_get`, dan tool `*_search` lainnya) mengagregasi data dari semua organisasi tersebut secara otomatis.

**Peran Anda selalu ditegakkan** oleh backend Didit, per organisasi. Setiap tool dipetakan ke satu string izin backend (misalnya `write:sessions` untuk `didit_session_update_status`, `delete:sessions` untuk `didit_session_delete`); [referensi tool](https://docs.didit.me/id/integration/mcp/tools.md) menampilkannya untuk setiap tool. Server juga memeriksa izin tersebut sebelum mengirim permintaan, menggunakan izin yang dibawa respons introspeksi untuk organisasi Anda:

* Dalam mode `enforce`, tool yang tidak dapat dijalankan oleh peran Anda dikeluarkan dari `tools/list`. Jika tool tetap dipanggil, server mengembalikan error `missing_scope` yang menyebut izin tersebut (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* Dalam mode `shadow` (default server), setiap tool tercantum dan panggilan diteruskan ke backend. Backend menjawab `403` jika peran tidak memiliki izin; hasilnya hanya dicatat di audit log server.

Bagaimanapun, MCP tidak pernah memberikan lebih dari yang sudah diizinkan peran konsol Anda. `READER` dapat menampilkan daftar dan membaca; `OWNER` atau `ADMIN` dapat menulis dan menghapus.

### Masa berlaku token

Aplikasi yang disetujui mendapat sesi sendiri, terpisah dari sesi browser tempat Anda menyetujuinya. Token akses berlaku dalam waktu singkat. Klien menyegarkannya secara diam-diam dengan refresh token (`grant_types_supported` mencakup `refresh_token`), dan proses refresh mempertahankan scope aplikasi serta tetap terikat pada aplikasi tersebut. Jika proses refresh gagal (misalnya setelah Anda memutus koneksi aplikasi), klien menjalankan ulang **Masuk dengan Didit** pada panggilan berikutnya.

Keluar dari konsol tidak membuat Anda keluar dari aplikasi yang terhubung, dan memutus koneksi aplikasi tidak pernah mengeluarkan Anda dari mana pun.

### Memutus koneksi aplikasi

**1. Dari konsol**

**Settings → Authentication → Connected apps** mencantumkan setiap aplikasi yang sudah Anda setujui, beserta nama terdaftarnya dan izin yang diberikan. **Putuskan** langsung mengakhiri akses aplikasi tersebut: access token dan refresh token-nya berhenti berfungsi, dan tidak ada yang lain yang terpengaruh.

**2. Dari aplikasi (RFC 7009)**

Klien dapat melepaskan aksesnya sendiri dengan mengirim token ke `revocation_endpoint` milik server otorisasi, yang tercantum dalam metadata di `https://business.didit.me/.well-known/oauth-authorization-server`. Sesuai RFC 7009, panggilan yang berhasil selalu dijawab `200`, baik token masih aktif maupun tidak, sehingga respons tidak pernah memberi tahu Anda apakah token tersebut valid. `503` berarti pencabutan tidak dapat diterapkan: anggap token masih valid dan coba lagi.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **Mengapa tidak perlu kunci API?** Setiap tool MCP memanggil endpoint konsol yang berada dalam lingkup pengguna (`/organization/{org}/application/{app}/…`), yang mengotorisasi Bearer token dengan hak akses per peran dan **menolak `x-api-key`**. Kunci API aplikasi digunakan untuk memanggil [REST API](https://docs.didit.me/openapi-25.json) langsung dari backend Anda sendiri (misalnya membuat sesi), bukan untuk MCP ini. `didit_org_list_api_keys` menampilkan metadata kunci dengan nilainya disembunyikan; tool yang menampilkan kunci mentah disembunyikan pada connector yang di-hosting.

***

## Menghubungkan dari setiap klien

Setiap klien menjalankan alur yang sama; yang berbeda hanya cara Anda memberikan URL-nya.

> [tab] Claude
>
> Gunakan deep link yang ditampilkan Business Console di halaman integrasi. Link ini membuka claude.ai dengan dialog **Add custom connector** yang sudah terisi:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Konfirmasi, lalu selesaikan **Masuk dengan Didit**. Claude Desktop menggunakan URL yang sama di **Settings → Connectors → Add custom connector**. Detailnya ada di [Connect Claude](https://docs.didit.me/id/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Kemudian jalankan `/mcp` di dalam Claude Code untuk memulai login melalui browser.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor mendaftarkan dirinya sendiri dan membuka browser saat pertama kali digunakan.

> [tab] Klien generik
>
> Arahkan klien Streamable HTTP apa pun yang mendukung OAuth 2.1 ke `https://mcp.didit.me/mcp`. Klien tersebut harus:
>
> 1. Mengirim `POST /mcp`, menerima `401`, dan membaca `resource_metadata` dari `WWW-Authenticate`.
> 2. Mengambil `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`, lalu metadata server otorisasi di `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Mendaftar di `registration_endpoint` jika belum memiliki ID klien.
> 4. Menjalankan alur kode otorisasi dengan PKCE (S256) di `authorization_endpoint`, lalu menukar kode di `token_endpoint`.
> 5. Mengirim `Authorization: Bearer <access_token>` pada setiap `POST /mcp`.
>
> Klien tanpa dukungan OAuth dapat dijalankan melalui `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, yang menjalankan langkah 1–5 untuk mereka.

***

## Kegagalan autentikasi

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

`401` dari `/mcp` berarti token tidak disertakan, sudah kedaluwarsa, atau telah dicabut. Klien sebaiknya memperbarui token atau menjalankan ulang **Masuk dengan Didit**.

`403` atau error `missing_scope` pada tool *tertentu* biasanya berarti salah satu dari dua hal: **peran** Anda tidak memiliki izin tersebut (misalnya `READER` yang mencoba melakukan penulisan), atau koneksi disetujui **tanpa scope** yang dibutuhkan tool itu. Itu tidak berarti seluruh koneksi rusak. Menghubungkan ulang dan menyetujui kedua scope memperbaiki kasus kedua; kasus pertama memerlukan perubahan peran.

Jika setiap tool gagal, periksa **Settings → Authentication → Connected apps** di konsol: aplikasi yang koneksinya diputus di sana harus disetujui ulang.

***

> [card] [Referensi tool](https://docs.didit.me/id/integration/mcp/tools.md)
>
> Apa yang dilakukan setiap tool, scope-nya, dan izin perannya.

> [card] [Lanjutan](https://docs.didit.me/id/integration/mcp/advanced.md)
>
> Peran, perilaku lintas aplikasi, dan self-hosting.


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