Referensi Auth API

Endpoint di bawah /auth/v2/ mengikuti Auth API v2 milik Duo: nama parameter, cara menandatangani, dan format jawabannya sama.

Dasar

Hal	Aturan
Alamat	`https://auth.wiracode.com`
Autentikasi	`Authorization: Basic base64(ikey:signature)` dan `Date` (caranya). `ping` dan `activation_qr` tanpa tanda tangan.
Parameter	GET: query string. POST: objek JSON (`application/json`, tanda tangan v5) atau form (`application/x-www-form-urlencoded`, v2).
Pengguna	`username`: email WiraPass pengguna. `user_id`: ID pengguna WiraPass (UUID).
Jawaban	`{"stat": "OK", "response": …}`. Bila gagal: `{"stat": "FAIL", "code": 40002, "message": …}`; status HTTP sama dengan tiga digit pertama code.
Bahasa	`status_msg` ditujukan untuk pengguna: bahasa Indonesia, atau bahasa Inggris dengan `Accept-Language: en`. `message` pada FAIL selalu bahasa Inggris, seperti Duo.

Contoh jawaban gagal

{
  "stat": "FAIL",
  "code": 40002,
  "message": "WiraPass does not offer the SMS factor. Use push, auto or passcode.",
  "message_detail": "factor"
}

Endpoint

Cek Layanan

GET/auth/v2/ping

Tanpa tanda tangan.

Tidak perlu tanda tangan. Pakai untuk memastikan layanan menjawab dan membandingkan jam server.

Jawaban 200. Jam server (detik Unix).

200 application/json

{
  "stat": "OK",
  "response": {
    "time": 1790497020
  }
}

Periksa Kunci dan Tanda Tangan

GET/auth/v2/check

Ditandatangani (caranya).

Menjawab OK bila integration key, secret key, dan cara menandatangani sudah benar.

Jawaban 200. Jam server (detik Unix).

200 application/json

{
  "stat": "OK",
  "response": {
    "time": 1790497020
  }
}

Kesalahan: 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Logo

GET/auth/v2/logo

Ditandatangani (caranya).

Ikon WiraPass sebagai PNG 128 x 128, untuk ditampilkan di halaman masuk Anda.

Jawaban 200. Gambar PNG.

Kesalahan: 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Mulai Pendaftaran Pengguna

POST/auth/v2/enroll

Ditandatangani (caranya).

Pengguna WiraPass mendaftar sendiri: pasang aplikasi, masuk dengan email ini, lalu aktifkan persetujuan. Endpoint ini memberi alamat halaman unduhan, kode QR-nya, dan kode aktivasi yang terikat ke email tersebut untuk dicek lewat enroll_status.

Bila akun WiraPass untuk email itu belum ada, user_id adalah ID sementara yang hanya berlaku untuk enroll_status. Untuk preauth dan auth, pakai username.

Parameter	Di	Wajib	Keterangan
`username`	badan	Ya	Email yang akan dipakai pengguna untuk masuk ke WiraPass. Wajib di WiraPass.
`valid_secs`	badan	Tidak	Masa berlaku kode aktivasi dalam detik. Bawaan 86400, dibatasi 60 sampai 604800.

Jawaban 200. Data aktivasi.

200 application/json

{
  "stat": "OK",
  "response": {
    "activation_barcode": "https://auth.wiracode.com/auth/v2/activation_qr",
    "activation_code": "q3Zb8Xk1LwT0vY7uR5nM2pQ9sD4fG6hJ",
    "activation_url": "https://auth.wiracode.com/#download",
    "expiration": 1790583420,
    "user_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "username": "rina@example.com"
  }
}

Kesalahan: 40001, 40002, 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Status Pendaftaran

POST/auth/v2/enroll_status

Ditandatangani (caranya).

Menjawab success bila email itu sudah punya HP penyetuju yang aktif, waiting bila belum, dan invalid bila kode tidak dikenal, kedaluwarsa, milik integrasi lain, atau user_id tidak cocok.

Parameter	Di	Wajib	Keterangan
`user_id`	badan	Ya	Nilai user_id dari enroll.
`activation_code`	badan	Ya	Nilai activation_code dari enroll.

Jawaban 200. Salah satu dari success, waiting, atau invalid.

200 application/json

{
  "stat": "OK",
  "response": "waiting"
}

Kesalahan: 40001, 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Bisakah Pengguna Ini Diminta Persetujuan?

POST/auth/v2/preauth

Ditandatangani (caranya).

Bila result bernilai auth, pengguna punya HP penyetuju aktif: lanjutkan ke auth. Bila enroll, pengguna belum memakai WiraPass atau belum mengaktifkan persetujuan: tolak dan arahkan ke enroll_portal_url. Bila deny, pengguna baru saja menekan "Bukan saya" untuk permintaan dari sistem Anda, jadi permintaan dijeda 15 menit. WiraPass tidak pernah menjawab allow di sini.

Daftar devices berisi HP penyetuju yang aktif. Kolom capabilities selalu memuat auto dan push; mobile_otp hanya ada bila pengguna sudah punya kode cadangan WiraPass. Bila tidak ada HP yang sedang masuk ke WiraPass, hasilnya tetap auth, tetapi push akan ditolak dan status_msg menyarankan kode cadangan.

Parameter	Di	Wajib	Keterangan
`username`	badan	Salah satu	Email WiraPass pengguna (tidak peka huruf besar kecil). Kirim username atau user_id, jangan keduanya.
`user_id`	badan	Salah satu	ID pengguna WiraPass (UUID). Pengganti username.
`ipaddr`	badan	Tidak	Alamat IP orang yang sedang masuk. Pada auth, alamat ini tampil di HP pengguna.
`hostname`	badan	Tidak	Nama perangkat yang dipakai untuk masuk. Pada auth, tampil sebagai perangkat.
`trusted_device_token`	badan	Tidak	Diterima, tetapi diabaikan (WiraPass tidak mengingat perangkat).
`client_supports_verified_push`	badan	Tidak	Diterima, tetapi diabaikan.

Jawaban 200. Salah satu dari auth, enroll, atau deny.

200 application/json

{
  "stat": "OK",
  "response": {
    "result": "auth",
    "status_msg": "Akun aktif.",
    "devices": [
      {
        "device": "9c8b7a6f-5e4d-4c3b-8a29-18f7e6d5c4b3",
        "type": "phone",
        "name": "Samsung SM-A546E",
        "number": "",
        "display_name": "Samsung SM-A546E",
        "capabilities": [
          "auto",
          "push",
          "mobile_otp"
        ]
      }
    ]
  }
}

Kesalahan: 40001, 40002, 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Minta Persetujuan atau Periksa Kode

POST/auth/v2/auth

Ditandatangani (caranya).

Dengan factor push (atau auto), permintaan dikirim ke semua HP penyetuju pengguna yang sedang masuk ke WiraPass. Tanpa async, panggilan menunggu sampai pengguna menjawab atau waktu habis (60 detik). Dengan async=1, jawabannya langsung berupa txid untuk auth_status.

Dengan factor passcode, server memeriksa kode cadangan 6 digit dari aplikasi WiraPass. Setiap kode hanya berlaku sekali, ada 5 percobaan per 5 menit per pengguna, dan kode terkunci setelah 10 kali salah berturut-turut (status locked_out).

Factor sms dan phone tidak tersedia di WiraPass dan ditolak dengan 40002.

Parameter	Di	Wajib	Keterangan
`username`	badan	Salah satu	Email WiraPass pengguna (tidak peka huruf besar kecil). Kirim username atau user_id, jangan keduanya.
`user_id`	badan	Salah satu	ID pengguna WiraPass (UUID). Pengganti username.
`factor`	badan	Ya	Nilai auto sama dengan push.
`device`	badan	Tidak	Isi auto (bawaan) atau id salah satu HP dari preauth. Permintaan tetap tampil di semua HP penyetuju pengguna.
`async`	badan	Tidak	Isi 1 agar langsung mendapat txid tanpa menunggu.
`type`	badan	Tidak	Judul permintaan di HP. Bawaan: "Masuk ke <nama integrasi>".
`display_username`	badan	Tidak	Tampil sebagai akun di HP.
`pushinfo`	badan	Tidak	Pasangan key=value ter-URL-encode, kurang dari 20000 byte. Yang dipakai: app (juga from, application), account (user, username), ip (ipaddr), location, device (hostname). Kunci lain diabaikan.
`passcode`	badan	Tidak	Wajib untuk factor passcode: kode cadangan 6 digit.
`ipaddr`	badan	Tidak	Alamat IP orang yang sedang masuk. Pada auth, alamat ini tampil di HP pengguna.
`hostname`	badan	Tidak	Nama perangkat yang dipakai untuk masuk. Pada auth, tampil sebagai perangkat.

Jawaban 200. Tanpa async: result dan status akhir. Dengan async: txid.

200 application/json

{
  "stat": "OK",
  "response": {
    "result": "allow",
    "status": "allow",
    "status_msg": "Disetujui. Anda bisa masuk."
  }
}

Kesalahan: 40001, 40002, 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Status Permintaan

GET/auth/v2/auth_status

Ditandatangani (caranya).

Long-poll: bila masih menunggu, server menunggu sampai 8 detik untuk perubahan sebelum menjawab waiting. Panggil lagi selama result = waiting. Hanya txid milik integrasi Anda sendiri.

Parameter	Di	Wajib	Keterangan
`txid`	query	Ya	Nilai txid dari auth.

Jawaban 200. Salah satu dari waiting, allow, atau deny, beserta status.

200 application/json

{
  "stat": "OK",
  "response": {
    "result": "waiting",
    "status": "pushed",
    "status_msg": "Permintaan masuk sudah dikirim ke HP Anda. Buka WiraPass untuk menyetujui."
  }
}

Kesalahan: 40001, 40002, 40101, 40102, 40103, 40104, 40105, 40106, 42901 (artinya).

Kode QR Halaman Unduhan

GET/auth/v2/activation_qr

Tanpa tanda tangan.

Tanpa tanda tangan. Gambar yang ditunjuk activation_barcode dari enroll.

Jawaban 200. Gambar PNG.