# Autentikasi Dua Faktor

Pocket Alert mendukung autentikasi dua faktor TOTP di dasbor web maupun aplikasi mobile. Setelah diaktifkan, kata sandi saja tidak lagi bisa membuka akun Anda.

Atur di [Akun → Keamanan](https://pocketalert.app/account/security).

## Cara mengaturnya

1. Buka **Akun → Keamanan** dan mulai pengaturan. Anda akan mendapatkan kode QR dan secret.
2. Pindai dengan aplikasi autentikator TOTP apa pun — Google Authenticator, 1Password, Authy, Bitwarden.
3. Masukkan kode enam digit untuk mengonfirmasi. Autentikasi dua faktor baru benar-benar aktif setelah kode yang benar dimasukkan.
4. Simpan kode pemulihan yang ditampilkan. Setiap kode hanya bisa digunakan sekali.

> **Tip: Pengaturan yang terhenti tetap aman**
>
> Memulai pengaturan baru tidak mengubah autentikasi dua faktor Anda yang sudah ada. Secret baru disimpan di slot tertunda dan hanya menggantikan yang aktif setelah Anda mengonfirmasi kode, sehingga menutup tab di tengah proses tidak akan mengunci Anda.

## Perubahan pada proses masuk

Dengan autentikasi dua faktor aktif, `POST /v1/auth/login` tidak lagi mengembalikan JWT. Sebagai gantinya, ia mengembalikan tantangan berumur pendek:

```json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}
```

Tukarkan tantangan beserta kode dengan token yang sebenarnya:

```
POST https://api.pocketalert.app/v1/auth/2fa/login
```

```bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'
```

Pertukaran yang berhasil mengembalikan payload yang sama seperti proses masuk biasa — `token`, `name`, `email`, `avatar`. Field `code` menerima kode TOTP enam digit atau salah satu kode pemulihan Anda.

Tantangan berlaku selama **5 menit**.

## Kunci API tidak terpengaruh

> **Info: Skrip tetap berjalan**
>
> Autentikasi dua faktor berlaku untuk proses masuk interaktif. Kunci API dari [Kunci API](https://pocketalert.app/account/apikeys) melakukan autentikasi dengan header `Token` dan tidak diminta tantangan tambahan — cron job, pipeline CI, dan hook pemantauan Anda tetap mengirim notifikasi seperti sebelumnya.
>
> Inilah alasan kunci API sebaiknya dibatasi per layanan: mencabut satu kunci tidak mengganggu yang lain.

## Kode pemulihan

Kode pemulihan hanya bisa digunakan sekali dan dikonsumsi secara atomik — dua proses masuk paralel tidak dapat memakai kode yang sama. Buat set baru kapan saja dari **Akun → Keamanan**; menerbitkan kode baru akan membatalkan kode lama.

Kehilangan autentikator sekaligus kode pemulihan? Hubungi dukungan. Tidak ada jalan pintas mandiri, dan memang itulah tujuannya.

## Perlindungan dari serangan brute-force

Lima kode yang salah akan mengunci akun selama **15 menit**, dan percobaan berikutnya akan mengembalikan `429`. Penghitung direset setelah proses masuk berhasil, serta saat autentikasi dua faktor diaktifkan atau dinonaktifkan. Karena tantangan tetap berlaku penuh selama lima menit, batas percobaan inilah — bukan masa berlaku tantangan — yang membuat penebakan kode enam digit menjadi tidak praktis.

## Notifikasi email

Anda akan menerima email setiap kali autentikasi dua faktor diaktifkan atau dinonaktifkan pada akun Anda. Jika email itu muncul dan Anda tidak merasa melakukannya, segera ubah kata sandi Anda.

## Endpoint

| Method | Endpoint | Fungsi |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | Apakah autentikasi dua faktor aktif, dan berapa kode pemulihan yang tersisa |
| `POST` | `/v1/auth/2fa/setup` | Memulai pendaftaran — mengembalikan secret dan payload QR |
| `POST` | `/v1/auth/2fa/enable` | Mengonfirmasi kode dan mengaktifkan autentikasi dua faktor |
| `POST` | `/v1/auth/2fa/disable` | Menonaktifkan autentikasi dua faktor — memerlukan kode dan kata sandi Anda |
| `POST` | `/v1/auth/2fa/recovery-codes` | Menerbitkan set kode pemulihan baru |
| `POST` | `/v1/auth/2fa/login` | Menukar tantangan + kode dengan JWT (tanpa header autentikasi) |

Setiap endpoint kecuali `/auth/2fa/login` memerlukan sesi yang sudah terautentikasi.

## Terkait

- [Login](https://info.pocketalert.app/api/user/login.md) — langkah pertama dari alur masuk
- [Pengantar](https://info.pocketalert.app/intro.md) — ikhtisar autentikasi
