> ## 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. # Buat Step-Up Autentikasi | Didit Authentication API > POST /step-up/ menerapkan aturan step-up Anda sebelum tindakan sensitif. Mengembalikan required false atau URL verifikasi untuk pengguna. > [!WARNING] > > Autentikasi adalah fitur baru. Endpoint-endpoint ini dilayani oleh penerbit aplikasi Anda, seperti `https://.auth.didit.me`, dan tidak pernah menggunakan kunci API Didit Anda. Parameter query `step_up` dan `status` pada `return_to` Anda hanya memberi tahu aplikasi Anda untuk memeriksa. Sebelum bertindak, baca step-up dengan [Dapatkan step-up](https://docs.didit.me/id/authentication/api-reference/retrieve-step-up.md) dan lanjutkan hanya jika `status` bernilai `approved`. ## OpenAPI ````yaml id/openapi-authentication.json POST /step-up/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- Endpoint yang menghadap ke server dari Didit Authentication, produk masuk (sign-in) untuk pengguna akhir aplikasi Anda. Authentication adalah fitur **baru** dan akan tersedia di lingkungan produksi pada rilis 2026-11-01. ## Base URL Setiap aplikasi adalah penerbit (issuer) OpenID Connect miliknya sendiri, dan setiap endpoint di bawah ini dilayani di root dari penerbit tersebut: - `https://.auth.didit.me` untuk aplikasi live, atau `https://.sandbox.auth.didit.me` untuk aplikasi sandbox. - Domain kustom Anda sendiri, setelah aktif. Domain tersebut kemudian menggantikan host default sebagai penerbit: token baru mencantumkannya di `iss`, discovery mengarah ke sana, dan kunci yang dapat dipublikasikan berubah. Token akses yang diterbitkan di bawah host default akan gagal di `/session/`, `/step-up/`, dan `/monitoring-token/` hingga token tersebut diperbarui. Lingkungan live dan sandbox adalah aplikasi terpisah, sehingga keduanya merupakan penerbit terpisah dengan kunci terpisah. Kunci yang dapat dipublikasikan adalah `pk_live_` (live) atau `pk_test_` (sandbox) diikuti oleh encoding base64url tanpa padding dari penerbit, tanpa garis miring penutup: lakukan decode untuk menemukan penerbitnya. Kunci ini adalah pengidentifikasi publik, bukan kredensial. Endpoint JSON yang sama juga dilayani di bawah `https://apx.didit.me/auth/v2/authentication/{application_id}/`. Token selalu mencantumkan penerbit di atas, alamat mana pun yang menerbitkannya. ## Kredensial Endpoint ini tidak pernah menerima kunci API Didit Anda atau token konsol. - Discovery, JWKS, dan `POST /token/` tidak memerlukan kredensial. Klien bersifat publik: tidak ada client secret, dan kode otorisasi terikat pada verifier PKCE-nya (`S256`). `client_id` adalah ID aplikasi Anda. - `/session/`, `/step-up/`, dan `/monitoring-token/` menerima token akses pengguna: `Authorization: Bearer `. Setiap panggilan yang berhasil dihitung sebagai aktivitas pada sesi, sehingga memulai ulang batas waktu tidak aktif (idle timeout) sesi tersebut. ## Body permintaan Setiap endpoint yang menerima body mendukung format JSON, form-encoded, dan multipart. Dokumen ini mencantumkan JSON, ditambah form-encoded untuk `POST /token/` sebagaimana yang dikirimkan oleh klien OAuth. Kolom yang tidak diterima oleh endpoint akan menghasilkan `400 {"": "unknown_field"}`. ## Token - **Token akses**: JWT ES256 dengan header `typ: at+jwt`, berlaku paling lama 5 menit dan tidak pernah lebih lama dari sesinya. Klaim: `AccessTokenClaims`. - **Token ID**: JWT ES256 dengan header `typ: JWT`. Klaim: `IDTokenClaims`. Token ini tidak pernah diterima sebagai token akses. - **Token pembaruan**: string acak yang dirotasi pada setiap penggunaan. Mengirimkan token pembaruan yang sudah digunakan kembali akan mencabut sesi. Verifikasi token dengan kunci dari `GET /.well-known/jwks.json`: algoritma harus berupa `ES256`, `typ` harus cocok dengan tipe token, `iss` harus sama dengan penerbit yang Anda konfigurasikan, dan `aud` harus sama dengan ID aplikasi Anda. Verifikasi offline hanya melihat sesi yang dicabut setelah token aksesnya kedaluwarsa; `GET /session/` adalah pemeriksaan instan. ## Error | Body | Kapan | | --- | --- | | `{"error": ""}` | Error dari `POST /token/`, semuanya dengan status `400`, dalam bentuk body [RFC 6749 bagian 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client`, dan `mfa_required` dari Didit. Error layanan: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` atau `{"": ""}` | Kolom permintaan gagal divalidasi. `non_field_errors` menunjukkan aturan lintas kolom, dan `unknown_field` menunjukkan kolom yang tidak diterima oleh endpoint. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (aplikasi atau step-up tidak dikenal), dan `429` (batas laju). Juga `400` untuk body yang tidak dapat di-parse (`JSON parse error - ...`), `405` untuk metode yang tidak dilayani oleh endpoint, dan `415` untuk `Content-Type` yang tidak didukung. | Status `401` juga membawa `WWW-Authenticate: Bearer`, dan `429` membawa `Retry-After` dalam detik. Ada dua penolakan yang bukan berupa JSON. Alamat yang bukan merupakan penerbit akan ditolak sebelum mencapai endpoint ini, misalnya dengan `404` kosong untuk nama `*.auth.didit.me` yang tidak digunakan. `step_up_id` yang bukan merupakan UUID akan menghasilkan halaman `404`. ## Batas laju Sebuah permintaan harus melewati dua lapisan. **Batas endpoint**, dihitung per alamat IP klien, per aplikasi, dan per endpoint: - Discovery dan JWKS: 1,200 permintaan per menit dan 12,000 per jam. - Setiap endpoint lainnya: 30 permintaan per menit dan 300 per jam. `GET` dan `DELETE /session/` berbagi satu hitungan. Melebihi batas: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, atau `3600 seconds` untuk batas per jam. **Proteksi bot**, pada setiap `POST` dan `DELETE`. Bucket-nya digunakan bersama oleh semua permintaan `POST` dan `DELETE` aplikasi, termasuk langkah masuk yang di-hosting, dan diisi ulang terus-menerus: - 60 permintaan per menit per alamat IP klien. - 30 permintaan per menit per perangkat, untuk permintaan yang mengidentifikasi perangkatnya, seperti yang dilakukan oleh SDK browser dan native. - 3,000 permintaan per menit untuk seluruh aplikasi, di seluruh alamat IP. Pembaruan token (`POST /token/` dengan `grant_type=refresh_token`) menggunakan bucket tersendiri: 6,000 per menit untuk seluruh aplikasi. Melebihi bucket: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` jika N bernilai 1). Bucket per IP mencakup seluruh endpoint, sehingga satu alamat yang mencampur panggilan token, step-up, dan keluar (sign-out) dapat mengosongkannya sebelum mencapai batas endpoint apa pun. Bucket aplikasi menghitung setiap klien dari aplikasi tersebut, termasuk browser. Kedua lapisan merespons sebelum endpoint dijalankan, sehingga permintaan yang mendapatkan `429` tidak dijalankan: coba lagi setelah `Retry-After`, termasuk pembaruan. ## Permintaan browser Permintaan yang membawa header `Origin` harus berasal dari salah satu origin milik aplikasi itu sendiri atau origin yang diizinkan, atau akan mendapatkan `403 origin_not_allowed`. Permintaan server-ke-server tidak mengirimkan `Origin`. ## Tidak dibahas di sini Rute-rute ini melayani halaman yang di-hosting, SDK browser dan native, serta agen AI. Rute ini bukan bagian dari kontrak server, dan SDK server tidak memanggilnya: - Langkah masuk: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*`, dan `/protection/complete/`. - Halaman yang di-hosting dan callback: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/`, serta file asosiasi aplikasi native di bawah `/.well-known/`. - Akses agen: `/agents/*` dan `/grants/`, termasuk `GET /agents/session/`, pemeriksaan live untuk token akses agen AI. Akses agen bukan bagian dari versi kontrak ini. - API manajemen konsol untuk Authentication, yang menggunakan sesi konsol. Event Authentication belum dikirimkan sebagai webhook, sehingga dokumen ini tidak mendefinisikan webhook apa pun. servers: - url: https://{issuer} description: 'Penerbit aplikasi Anda: asal proses masuknya.' variables: issuer: default: your-app.auth.didit.me description: >- Host penerbit: `.auth.didit.me` (produksi), `.sandbox.auth.didit.me` (sandbox), atau domain kustom aktif Anda. security: [] tags: - name: Issuer description: Kunci penemuan dan penandatanganan, untuk memverifikasi token. - name: Tokens description: Grant untuk kode otorisasi dan refresh. - name: Sessions description: Periksa dan akhiri sesi yang terkait dengan token akses. - name: Step-ups description: Verifikasi sebelum tindakan sensitif. - name: Monitoring description: Kredensial perangkat untuk event pemantauan transaksi. paths: /step-up/: post: tags: - Step-ups summary: Buat step-up description: >- Menanyakan apakah orang tersebut harus melakukan verifikasi sebelum tindakan sensitif, menggunakan aturan step-up yang Anda tetapkan untuk aplikasi. - `200 {"required": false}`: tidak ada aturan yang berlaku, lanjutkan. - `201`: arahkan orang tersebut ke `verification_url`. Mereka kembali ke `return_to` dengan `step_up=&status=approved`, tetapi kueri tersebut tidak membuktikan apa pun: baca step-up dengan `GET /step-up/{step_up_id}/` dan bertindak hanya jika `approved`. Step-up tidak pernah gagal terbuka: ketika verifikasi tidak tersedia, tindakan tetap diblokir. operationId: authentication_create_step_up requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StepUpRequest' examples: Payout: summary: Sebelum pembayaran value: action: payout amount: '900.00' currency: USD return_to: https://app.example.com/payouts/confirm Bank: summary: Sebelum mengubah rekening bank value: action: bank return_to: https://app.example.com/settings/bank responses: '200': description: Tidak ada aturan yang berlaku. headers: Cache-Control: description: >- Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache. schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/StepUpNotRequired' examples: NotRequired: summary: Lanjutkan value: required: false '201': description: Orang tersebut harus melakukan verifikasi terlebih dahulu. headers: Cache-Control: description: >- Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache. schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/StepUpRequired' examples: Required: summary: Swafoto sebelum pembayaran value: id: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: payout method: selfie status: pending level: null amount: '900.00' currency: USD created_at: '2026-10-17T10:41:14.894632Z' completed_at: null expires_at: '2026-10-17T11:11:14.894581Z' required: true verification_url: >- https://your-app.auth.didit.me/verify/?verification=1nSX7HJCXAP9XPA9AeJfQxIuPk2GkG0dGSOzCA2Zpww expires_in: 1800 '400': description: >- Kolom tidak ada atau tidak valid. `return_to: invalid_redirect_uri` berarti suatu aturan berlaku dan `return_to` bukan salah satu dari URI pengalihan aplikasi. headers: Cache-Control: description: >- Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache. schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/FieldErrors' examples: MissingAmount: summary: Pembayaran tanpa jumlah value: amount: - required InvalidReturnTo: summary: return_to tidak terdaftar value: return_to: invalid_redirect_uri UnknownAction: summary: Tindakan tidak didukung value: action: - '"withdraw" is not a valid choice.' '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: StepUpRequest: type: object description: Tindakan sensitif yang akan diambil orang tersebut. required: - action - return_to additionalProperties: false properties: action: type: string enum: - payout - bank - contact description: >- `payout` (penarikan atau transfer dana), `bank` (menambahkan atau mengubah rekening bank) atau `contact` (mengubah email atau nomor telepon). Payout juga menerapkan aturan perangkat baru. amount: type: string pattern: ^[0-9]{1,16}(\.[0-9]{1,2})?$ description: >- Wajib untuk `payout`: jumlah, hingga dua desimal. Angka JSON juga diterima. example: '900.00' currency: type: string pattern: ^[A-Z]{3}$ description: >- Kode ISO 4217 dari `amount`. Default ke mata uang aturan pembayaran; pembayaran dalam mata uang lain selalu diperiksa. example: USD return_to: type: string maxLength: 2048 description: >- Tujuan pengguna kembali setelah memverifikasi, dengan tambahan `step_up=&status=approved`. Saat suatu aturan berlaku, nilai ini harus merupakan salah satu URI pengalihan aplikasi; saat tidak ada yang berlaku, nilai ini tidak diperiksa. example: https://app.example.com/payouts/confirm StepUpNotRequired: type: object description: 'Tidak ada aturan yang berlaku: lanjutkan tindakan.' required: - required properties: required: type: boolean enum: - false StepUpRequired: description: Step-up baru. Arahkan pengguna ke `verification_url`. allOf: - $ref: '#/components/schemas/StepUp' - type: object required: - required - verification_url - expires_in properties: required: type: boolean enum: - true verification_url: type: string format: uri description: >- Halaman yang di-hosting tempat orang tersebut melakukan verifikasi; buka di browser orang tersebut. Halaman ini berfungsi hingga step-up disetujui atau kedaluwarsa, sehingga orang yang ditolak dapat mencoba lagi dari halaman ini. example: >- https://your-app.auth.didit.me/verify/?verification=1nSX7HJCXAP9XPA9AeJfQxIuPk2GkG0dGSOzCA2Zpww expires_in: type: integer description: 'Detik selama step-up tetap terbuka: 1800.' example: 1800 FieldErrors: title: Field errors type: object description: >- Kesalahan validasi berdasarkan kolom. Nilai berupa daftar pesan, atau satu kode tunggal (`unknown_field`, `invalid_redirect_uri`). `non_field_errors` menampung aturan lintas kolom. additionalProperties: oneOf: - type: string - type: array items: type: string StepUp: type: object description: Verifikasi yang harus dilewati seseorang sebelum tindakan dilakukan. required: - id - rule - method - status - level - amount - currency - created_at - completed_at - expires_at properties: id: type: string format: uuid example: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: type: string enum: - payout - device - bank - contact description: >- Aturan yang memintanya. Jika beberapa aturan berlaku, aturan dengan metode terkuat yang digunakan. example: payout method: type: string enum: - liveness - selfie - full_id description: >- Tindakan yang dilakukan orang tersebut: `liveness`, `selfie` (liveness yang dicocokkan dengan wajah yang sudah dimiliki Didit) atau `full_id` (dokumen dan swafoto). Ketika Didit belum memiliki data wajah orang tersebut, `selfie` menjadi `full_id` setelah mereka membuka `verification_url`. example: selfie status: type: string enum: - pending - review - approved - declined - expired - superseded description: >- Bertindaklah hanya pada `approved`. `review` menunggu peninjauan tim Anda. `declined` tidak bersifat final selama `verification_url` berfungsi: orang tersebut dapat mencoba lagi, dan peningkatan verifikasi kembali ke `pending`. `superseded` berarti pemeriksaan lain mengambil alih verifikasinya, atau hasilnya bukan untuk peningkatan verifikasi ini: buat yang baru. example: pending level: type: string nullable: true enum: - liveness - liveness_face_match - full_id - null description: Tingkat yang dicapai verifikasi, setelah disetujui. example: null amount: type: string nullable: true description: Jumlah pembayaran keluar, dua desimal. example: '900.00' currency: type: string nullable: true example: USD created_at: type: string format: date-time example: '2026-10-17T10:41:14.894632Z' completed_at: type: string format: date-time nullable: true example: null expires_at: type: string format: date-time description: >- 30 menit setelah pembuatan. Pembacaan step-up terlebih dahulu mengumpulkan hasil apa pun yang dicapai verifikasinya, sehingga masih dapat terbaca `approved`, `review`, atau `declined` setelah waktu ini; yang masih `pending` akan terbaca `expired`. example: '2026-10-17T11:11:14.894581Z' Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: Error OAuth (RFC 6749 bagian 5.2) atau error layanan. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- Token akses tidak ada, salah format, kedaluwarsa, ditandatangani oleh penerbit atau kunci lain, merupakan token ID, token agen, atau digantikan oleh token refresh; atau sesinya telah dicabut, habis karena tidak aktif, melewati masa berlakunya atau tidak lagi memenuhi kebijakan MFA Anda, atau orang tersebut diblokir atau email mereka tidak lagi terverifikasi. Arahkan orang tersebut untuk masuk lagi. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache.' schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Token akses ditolak value: detail: invalid_token OriginNotAllowed: description: >- Permintaan membawa `Origin` yang bukan milik aplikasi dan tidak terdapat dalam daftar origin yang diizinkan. Permintaan server tidak mengirimkan `Origin`. headers: Cache-Control: description: 'Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache.' schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Asal tidak diizinkan value: detail: origin_not_allowed ApplicationNotFound: description: >- Alamat milik suatu aplikasi, tetapi Autentikasi tidak aktif untuk aplikasi tersebut; pada alamat `apx.didit.me`, ID aplikasi tidak diketahui. Alamat yang bukan milik aplikasi mana pun ditolak sebelum mencapai endpoint, dan respons tersebut bukan JSON. headers: Cache-Control: description: 'Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache.' schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: ApplicationNotFound: summary: Aplikasi tidak dikenal value: detail: No Configuration matches the given query. RateLimited: description: >- Terlalu banyak permintaan dari alamat ini untuk endpoint ini, atau, pada `POST` atau `DELETE`, bucket perlindungan bot kosong. Tidak ada yang dijalankan: tunggu selama `Retry-After` detik, lalu coba lagi. headers: Retry-After: description: Detik untuk menunggu sebelum mencoba lagi. schema: type: integer example: 60 Cache-Control: description: 'Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache.' schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Batas endpoint value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Batas perlindungan bot (POST dan DELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- Layanan yang dibutuhkan permintaan sedang tidak tersedia untuk sementara. Coba lagi dengan backoff. headers: Cache-Control: description: 'Selalu `no-store`: jangan pernah menyimpan respons ini dalam cache.' schema: type: string example: no-store Pragma: description: Selalu `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: Coba lagi nanti value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- Token akses orang tersebut dari `POST /token/`: JWT ES256 dengan header `typ: at+jwt`, berlaku paling lama 5 menit. Bukan kunci API Didit Anda. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.