> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mertani.co.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

## Base URL

Semua permintaan data ke Mertani menggunakan base URL berikut dan **wajib** menggunakan `HTTPS`. Permintaan melalui `HTTP` tidak didukung.

```text theme={null}
https://app.mertani.co.id/external/v1
```

***

## Metode Akses

Mertani menyediakan dua metode akses untuk mengambil data perangkat:

| Metode                   | Keterangan                                  | Endpoint                                                    |
| ------------------------ | ------------------------------------------- | ----------------------------------------------------------- |
| **Basic Authentication** | Akses dengan username dan password          | `/devices`, `/devices/{device_id}/data`                     |
| **Public Access**        | Akses tanpa autentikasi menggunakan API Key | `/{api-key}/devices`, `/{api-key}/devices/{device_id}/data` |

***

## Basic Authentication

Metode autentikasi menggunakan username (`api_key`) dan password (`secret_key`) yang dikirim melalui header `Authorization`.

### Kapan Digunakan

* Akses data perangkat milik instansi Anda
* Integrasi backend/server yang memerlukan keamanan tinggi
* Akses data secara programatik

### Kredensial

| Field        | Peran    | Keterangan                       |
| ------------ | -------- | -------------------------------- |
| `api_key`    | Username | Mengidentifikasi client/instansi |
| `secret_key` | Password | Memvalidasi hak akses            |

> `api_key` dan `secret_key` bersifat statis dan tidak kedaluwarsa, kecuali dicabut atau diganti oleh pihak Mertani.

### Cara Membuat Header Authorization

Ikuti tiga langkah berikut untuk menghasilkan header yang valid:

<Steps>
  <Step title="Gabungkan kredensial">
    Satukan `api_key` dan `secret_key` dengan tanda titik dua (`:`):

    ```text theme={null}
    api_key:secret_key
    ```

    Contoh:

    ```text theme={null}
    mertani_user:mertani_secret
    ```
  </Step>

  <Step title="Encode ke Base64">
    Encode string tersebut menggunakan Base64:

    ```text theme={null}
    bWVydGFuaV91c2VyOm1lcnRhbmlfc2VjcmV0
    ```
  </Step>

  <Step title="Kirim sebagai header">
    Sertakan hasil encode pada header `Authorization`:

    ```bash theme={null}
    Authorization: Basic bWVydGFuaV91c2VyOm1lcnRhbmlfc2VjcmV0
    ```
  </Step>
</Steps>

### Contoh Request

```bash theme={null}
curl -X GET "https://app.mertani.co.id/external/v1/devices" \
  -H "Authorization: Basic bWVydGFuaV91c2VyOm1lcnRhbmlfc2VjcmV0"
```

### Endpoint yang Mendukung Basic Auth

| Endpoint                        | Deskripsi                       |
| ------------------------------- | ------------------------------- |
| `GET /devices`                  | Mengambil daftar perangkat      |
| `GET /devices/{device_id}/data` | Mengambil data sensor perangkat |

***

## Public Access

Metode akses tanpa username atau password menggunakan **API Key** yang disertakan langsung dalam URL endpoint.

### Kapan Digunakan

* Akses data secara publik tanpa autentikasi
* Integrasi sistem yang tidak mendukung header authorization
* demonstrasi atau pengujian API

### Cara Mendapatkan API Key

**API Key** diperoleh dari pihak Mertani. Contoh API Key:

```text theme={null}
mertani-abc123
```

### Format Endpoint

Tambahkan API Key sebagai path parameter pada URL:

```text theme={null}
https://app.mertani.co.id/external/v1/{api-key}/devices
```

### Contoh Request

```bash theme={null}
curl -X GET "https://app.mertani.co.id/external/v1/mertani-abc123/devices"
```

### Endpoint yang Mendukung Public Access

| Endpoint                                  | Deskripsi                       |
| ----------------------------------------- | ------------------------------- |
| `GET /{api-key}/devices`                  | Mengambil daftar perangkat      |
| `GET /{api-key}/devices/{device_id}/data` | Mengambil data sensor perangkat |

<Callout type="warning">
  Public Access hanya dapat mengakses data milik instansi yang terkait dengan API Key tersebut. Tidak diperlukan Basic Authentication.
</Callout>

***

## Perbandingan Metode Akses

| Aspek       | Basic Authentication | Public Access        |
| ----------- | -------------------- | -------------------- |
| Autentikasi | Username + Password  | Tidak ada            |
| Keamanan    | Tinggi               | Sedang               |
| Endpoint    | `/devices`           | `/{api-key}/devices` |
| Penggunaan  | Backend/Server       | Public/Testing       |

***

## Keamanan Kredensial

<Warning title="Jangan ekspos API Key">
  `api_key` dan `secret_key` bersifat sangat sensitif. Jangan pernah menyimpan atau mengekspos kredensial ini di frontend (client-side), repository publik, atau tempat yang tidak aman.
</Warning>

**Best practice penyimpanan dan pengelolaan:**

* Simpan di **server-side environment variables**, bukan di source code
* Gunakan **secret manager** (AWS Secrets Manager, GCP Secret Manager, atau sejenisnya) untuk lingkungan produksi
* Aktifkan **logging** untuk mendeteksi pola akses yang tidak wajar
* Lakukan **rotasi API key** secara berkala atau segera jika dicurigai bocor