> ## Documentation Index
> Fetch the complete documentation index at: https://api.sosmednext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autentikasi API

> Cara mengotentikasi request API dari sistem/server Anda ke sistem SosmedNext.

Setiap *request* yang dikirimkan ke endpoint API sistem SosmedNext wajib menyertakan **API Key** Anda yang unik.\
API Key ini bertindak sebagai paspor akun Anda agar sistem kami dapat memproses order atas nama Anda dan menagih/memotong saldo pada nilai yang tepat secara algoritmik dari saldo Anda.

Anda dapat menemukan API Key saat ini, atau membuat API Key yang baru (me-reset) di halaman **"Pengaturan Profil"** dalam Dashboard SosmedNext Anda.

<Warning>
  **JANGAN BAGIKAN API KEY ANDA KEPADA SIAPAPUN.**
  API Key memberikan kontrol penuh secara administratif ke saldo utama Anda. Peretas yang mengetahui API Key Anda dapat menghabiskan saldo server Anda. Jangan sekali-sekali menuliskan API Key di *frontend* code Anda (seperti tampilan HTML atau Javascript pada browser), selalu konfigurasikan dan panggil API Key Anda menggunakan *backend* server (seperti kode program PHP / Node.js backend).
</Warning>

## Cara Mengirimkan API Key

Sistem kami mendukung 3 (tiga) cara berbeda untuk mengirimkan API Key pada setiap request Anda. Anda dapat memilih salah satu metode yang paling mudah diintegrasikan atau didukung oleh library bahasa pemrograman / framework Anda:

### 1. Header `X-Api-Key` (Rekomendasi)

Pendekatan paling bersih adalah meletakkan key di Header Request custom, yaitu `X-Api-Key`.

```bash Auth with Header theme={null}
curl -X GET -H "X-Api-Key: YOUR_API_KEY" https://app.sosmednext.com/api/v1/balance
```

### 2. Header `Authorization: Bearer`

Jika sistem atau *framework frontend/backend* Anda sudah otomatis menggunakan skema `Bearer` token untuk *authorization*, Anda bisa memakainya.

```bash Auth with Bearer theme={null}
curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://app.sosmednext.com/api/v1/balance
```

### 3. Query Parameter `api_key`

Jika framework Anda tidak mengizinkan kustom HTTP Header (yang terjadi di beberapa sistem web lawas), Anda dapat meletakkannya langsung di URL query string.

```bash Auth with Query Params theme={null}
curl -X GET "https://app.sosmednext.com/api/v1/balance?api_key=YOUR_API_KEY"
```

***

## Memahami Response Error Authentication

Jika Anda mendapati konektivitas request tidak membuahkan hasil *success*, Anda kemungkinan menerima respons gagal pada HTTP code berikut karena berbagai alasan otentikasi. Jika API Key Anda keliru atau IP Server Anda dirantai/belum didaftarkan (bila kontrol fitur IP Whitelist sedang *ON*), Anda akan menerima *response HTTP Status 401 Unauthorized* atau *403 Forbidden*:

```json Response Error (401 - Unauthorized) theme={null}
{
  "error": "Invalid API key or inactive account"
}
```

```json Response Error (403 - Forbidden) theme={null}
{
  "error": "IP not whitelisted"
}
```

Pastikan Anda menangkap exception code `400`/`401`/`403`/`500` pada logika *try-catch* aplikasi Anda untuk menampilkan pesan error dengan rapi alih-alih merusak aplikasi antarmuka. Keamanan IP Whitelist selalu dapat disesuaikan sesuka hati Anda di panel pengguna Anda!