Hubungkan Agen AI ke APIPedia dengan Kode

Ketik "hubungkan platformku ke apipedia.id" di agen AI, buka link yang muncul, lalu tekan Setujui. Agen mendapat API key tanpa salin-tempel.

• Minta kode: POST https://api.apipedia.id/v1/device/code
• Poll token: POST https://api.apipedia.id/v1/device/token
• Halaman persetujuan: https://console.apipedia.id/device
• Halaman: https://apipedia.id/docs/device-code
• Panduan umum (autentikasi, format respons, kode error): https://apipedia.id/docs.md

Cara kerja singkat

Alur ini memakai OAuth 2.0 Device Authorization Grant (RFC 8628), cara yang sama seperti login TV atau CLI dengan kode. Cocok untuk agen yang tidak bisa membuka browser atau menerima redirect OAuth: Claude Code, agen CLI, runtime agen di server, dan sejenisnya.

1. Agen meminta kode ke POST /v1/device/code (tanpa token).
2. Agen menampilkan link persetujuan berisi kode 8 karakter, mis. 2WKM-NH3C.
3. Kamu membuka link, login, memeriksa nama agen, lalu menekan Setujui.
4. Sementara itu agen mem-poll POST /v1/device/token dan, setelah disetujui, menerima satu API key baru (apk_...) khusus untuknya.

Tanpa salin-tempel API key dan tanpa redirect URI. Kunci yang diterima berlaku untuk REST maupun server MCP.

Langkah-langkah

1. Di agenmu (Claude, Cursor, agen CLI, dsb.) ketik: "hubungkan platformku ke apipedia.id".
2. Agen memanggil POST https://api.apipedia.id/v1/device/code lalu berkata kepadamu: "Buka link ini: https://console.apipedia.id/device?code=2WKM-NH3C — login, cek nama agent-nya, centang kotaknya, lalu tekan Setujui."
3. Buka link itu. Kalau belum masuk, console meminta login lalu kembali ke halaman persetujuan dengan kodenya.
4. Periksa rinciannya: nama agen, platform, kode (harus sama dengan yang ditampilkan agen), waktu permintaan, dan asal permintaan (negara + IP tersamar).
5. Centang kotak "Saya mengenali agent ini dan memberi akses penuh ke akun APIPedia saya", lalu tekan Setujui. Kalau tidak mengenali permintaannya, tekan Tolak.
6. Kembali ke agen. Dalam beberapa detik agen menerima aksesnya dan melanjutkan tugas secara otomatis.

Kode berlaku 10 menit. Kalau kedaluwarsa, minta agen membuat kode baru.

Tiga cara menyetujui

Kode tidak peka huruf besar/kecil; spasi dan tanda hubung boleh dihilangkan (2wkm nh3c = 2WKM-NH3C).

Prompt siap tempel

Agen yang sudah memakai Skill APIPedia tahu alurnya dari kalimat "hubungkan platformku ke apipedia.id". Untuk agen lain, tempel prompt ini:

Hubungkan platform ini ke akun APIPedia saya (apipedia.id) dengan alur kode perangkat (RFC 8628). Jangan minta saya menyalin API key.

1. POST https://api.apipedia.id/v1/device/code dengan JSON {"client_name":"<nama platform/agen ini>","agent_name":"<nama agen>"}.
2. Tampilkan ke saya isi field "message" apa adanya (berisi link verification_uri_complete). Jangan tampilkan device_code.
3. Tiap "interval" detik (awalnya 5), POST https://api.apipedia.id/v1/device/token dengan JSON {"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}.
   - authorization_pending: tunggu lalu poll lagi.
   - slow_down: tambah jeda 5 detik (pakai nilai "interval" di respons).
   - access_denied atau expired_token: berhenti dan beri tahu saya.
4. Kalau berhasil, simpan access_token (apk_...) sebagai APIPEDIA_TOKEN tanpa menampilkannya ulang, lalu kirim header "Authorization: Bearer <token>" ke https://api.apipedia.id/v1 atau ke server MCP https://api.apipedia.id/v1/mcp.

Petunjuk lengkap: https://api.apipedia.id/v1/device dan https://apipedia.id/docs/device-code.md

API: minta kode

POST https://api.apipedia.id/v1/device/code, tanpa token. Body JSON:

curl -s -X POST https://api.apipedia.id/v1/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Claude Code","agent_name":"Agent Toko Budi"}'

Respons 200:

{
  "device_code": "Gm3c9V…(rahasia, 43 karakter)",
  "user_code": "2WKM-NH3C",
  "verification_uri": "https://console.apipedia.id/device",
  "verification_uri_complete": "https://console.apipedia.id/device?code=2WKM-NH3C",
  "expires_in": 600,
  "interval": 5,
  "message": "Buka link ini: https://console.apipedia.id/device?code=2WKM-NH3C - login, cek nama agent-nya, centang kotaknya, lalu tekan Setujui."
}

• device_code rahasia: dipakai hanya untuk poll, jangan ditampilkan ke pengguna.
• user_code 8 karakter XXXX-XXXX dari huruf dan angka tanpa I L O U 0 1 supaya tidak tertukar.
• expires_in 600 detik (10 menit), interval 5 detik.
• Gagal: 400 invalid_request bila client_name dan agent_name kosong; 429 slow_down bila lebih dari 20 permintaan kode per 15 menit dari satu IP.

Petunjuk mesin-terbaca untuk agen (amplop { is_success, message, data } berisi endpoint, grant type, dan langkah): GET https://api.apipedia.id/v1/device.

API: poll token

POST https://api.apipedia.id/v1/device/token, tanpa token, tiap interval detik. Body JSON atau form: device_code (wajib) dan grant_type (opsional, bila diisi harus urn:ietf:params:oauth:grant-type:device_code).

curl -s -X POST https://api.apipedia.id/v1/device/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}'

Selama belum selesai, server menjawab HTTP 400 dengan { "error", "error_description" }:

{ "error": "authorization_pending", "error_description": "Menunggu pengguna menyetujui di halaman /device." }

{ "error": "slow_down", "error_description": "Terlalu sering. Tunggu 10 detik di antara poll.", "interval": 10 }

Setelah disetujui, respons 200:

{
  "access_token": "apk_...",
  "token_type": "Bearer",
  "scope": "all",
  "api_key": "apk_...",
  "key_prefix": "apk_xxxxxxxx",
  "mcp_url": "https://api.apipedia.id/v1/mcp",
  "api_base_url": "https://api.apipedia.id/v1"
}

access_token (sama dengan api_key) adalah API key apk_ biasa dan hanya diserahkan sekali ke poll pertama. Tidak ada expires_in: kunci berlaku sampai dicabut. Simpan sebagai APIPEDIA_TOKEN, lalu kirim Authorization: Bearer apk_... ke https://api.apipedia.id/v1 atau https://api.apipedia.id/v1/mcp.

Contoh kode

Seluruh alur dalam satu skrip:

// Node.js 18+ (fetch bawaan)
const API = 'https://api.apipedia.id/v1';
const start = await fetch(`${API}/device/code`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ client_name: 'Skrip Toko Budi', agent_name: 'Agent Toko Budi' }),
}).then((r) => r.json());
console.log(start.message); // tampilkan link ke pengguna

let wait = start.interval;
for (;;) {
  await new Promise((r) => setTimeout(r, wait * 1000));
  const res = await fetch(`${API}/device/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: start.device_code }),
  });
  const body = await res.json();
  if (res.ok) {
    process.env.APIPEDIA_TOKEN = body.access_token; // simpan, jangan dicetak
    break;
  }
  if (body.error === 'authorization_pending') continue;
  if (body.error === 'slow_down') { wait = body.interval ?? wait + 5; continue; }
  throw new Error(`${body.error}: ${body.error_description}`); // access_denied, expired_token, invalid_grant
}

Akses yang diberikan dan cara mencabut

• Menekan Setujui membuat satu API key baru bernama Agent: <nama agen> dengan akses penuh ke seluruh API dan tool MCP APIPedia, tanpa masa berlaku.
• Kunci yang sama berlaku untuk REST dan MCP. Setiap panggilan dihitung ke kuota dan saldo akunmu.
• Mencabut akses: buka halaman Token API dan cabut kunci Agent: <nama>. Agen langsung terputus.
• Sebelum disetujui, Tolak membuat agen menerima access_denied. Setelah disetujui, permintaan tidak bisa ditolak lagi; cabut kuncinya.
• Butuh akses yang lebih sempit? Buat token berlingkup sendiri dan pakai Via prompt token.

Keamanan

• Setujui hanya permintaan yang kamu mulai sendiri. Kalau menerima link atau notifikasi yang tidak kamu minta, tekan Tolak.
• Cocokkan kodenya. Kode di halaman persetujuan harus sama dengan yang ditampilkan agen, dan nama agen serta platformnya harus kamu kenali.
• Kode berumur pendek. Berlaku 10 menit dan sekali pakai; kunci diserahkan ke satu poll saja.
• Hanya sesi console yang bisa menyetujui. API key tidak bisa dipakai untuk menyetujui agen lain, dan percobaan kode dibatasi 40 kali per 5 menit per akun supaya kode tidak bisa ditebak.
• Kode perangkat adalah rahasia agen. device_code tidak boleh ditampilkan agen; yang dibagikan ke pengguna hanya link dan user_code.

Cara lain menghubungkan agen

• Via MCP: tempel URL server MCP https://api.apipedia.id/v1/mcp ke Claude, ChatGPT, Cursor, atau VS Code lalu login OAuth. Cocok untuk klien yang mendukung MCP.
• Via prompt token: buat token API sendiri lalu berikan ke agen di prompt atau environment variable. Cocok untuk agen apa pun yang bisa melakukan HTTP request.

Ketiga cara berujung pada kredensial yang sama jenisnya: API key apk_ dengan kuota, penagihan, dan amplop respons yang sama. Tambahkan Skill APIPedia supaya agen mengenal setiap endpoint.