Keamanan Dokumentasi API: Apakah Spesifikasi Anda Aman di Git?

Keamanan dokumentasi API jarang diaudit, padahal developer memakai dokumentasi sebagai instruksi implementasi: endpoint, header autentikasi, payload, dan contoh kode sering langsung disalin ke produksi. API Anda mungkin sudah dilindungi dengan autentikasi, rate limit, dan security testing, tetapi spesifikasi OpenAPI, halaman Swagger UI, atau markdown autentikasi bisa saja berada di repositori Git atau static host yang tidak pernah ditinjau ulang. Pada 20 Mei 2026, GitHub mengonfirmasi bahwa penyerang mencuri data dari sekitar 3.800 repositori kode internal melalui ekstensi VS Code berbahaya yang terpasang di laptop karyawan. Pertanyaan yang perlu diajukan: jika seseorang diam-diam mengubah dokumentasi API yang sudah Anda publikasikan, apakah tim Anda dan konsumen API Anda akan menyadarinya?

Coba Apidog hari ini

TL;DR

Dokumentasi API yang aman harus memiliki:

• kontrol akses,
• versioning,
• integritas yang dapat diverifikasi,
• audit trail.

Docs-as-code di Git tetap valid untuk banyak tim karena memberi review dan histori perubahan. Namun, pendekatan ini menjadi risiko jika repositori publik tanpa access control, spesifikasi API tidak sinkron dengan API aktual, atau contoh endpoint/autentikasi dapat dimanipulasi tanpa terdeteksi.

Lapisan dokumentasi terkelola seperti Apidog menambahkan proteksi seperti password, allowlist IP/email, custom domain, versioning, dan dokumentasi yang tetap sinkron dengan desain API sebagai sumber kebenaran.

Mengapa pelanggaran GitHub relevan untuk dokumentasi API Anda

Insiden GitHub perlu dilihat sebagai pengingat praktis, bukan alasan untuk panik. Kelompok ancaman TeamPCP mengeksfiltrasi repositori internal GitHub dan menjual dataset tersebut di forum bawah tanah. Liputan BleepingComputer mengonfirmasi bahwa ekstensi VS Code berbahaya tersebut berasal dari marketplace resmi dan berjalan di perangkat karyawan. GitHub mengatakan tidak menemukan bukti bahwa data pelanggan di luar repositori internal terdampak, dan investigasi masih berjalan.

Masalah yang perlu Anda audit adalah ini: di mana dokumentasi API Anda disimpan, siapa yang bisa mengubahnya, dan apakah perubahan berbahaya akan terdeteksi?

Banyak tim menerbitkan Swagger UI ke GitHub Pages, memasang CNAME, lalu melupakannya selama bertahun-tahun. Repositori mungkin publik. Spesifikasi API adalah file terakhir yang digabungkan. Perubahan dokumentasi tidak selalu direview seketat perubahan kode aplikasi.

Padahal dokumentasi API adalah instruksi implementasi. Developer menyalin endpoint, bentuk request, header autentikasi, dan contoh token dari dokumentasi resmi. Jika penyerang dapat mengubah dokumentasi tersebut, mereka tidak hanya mengubah halaman teks; mereka mengubah instruksi yang mungkin masuk ke kode produksi konsumen API Anda.

Logika serupa juga muncul dalam tinjauan insiden lain. Tulisan kami tentang pelajaran keamanan API dari pelanggaran Vercel membahas bagaimana perubahan kecil pada permukaan yang dipercaya dapat menyebar ke luar.

Artikel ini membahas:

1. cara dokumentasi API yang disusupi dapat merugikan konsumen,
2. kapan docs-as-code di Git aman digunakan,
3. checklist dokumentasi API yang aman,
4. bagaimana lapisan dokumentasi terkelola membantu menutup celah.

Untuk konteks tambahan, lihat juga apa arti pelanggaran GitHub bagi alat API yang di-host sendiri dan keamanan kunci API ekstensi VS Code.

Apa yang bisa salah ketika repositori atau host dokumentasi API disusupi

Model ancamannya sederhana. Dokumentasi API Anda biasanya melewati tiga permukaan:

1. repositori Git,
2. pipeline CI/CD yang membangun dokumentasi,
3. host yang menyajikan dokumentasi.

Jika salah satu permukaan ini disusupi, dampaknya bisa langsung masuk ke implementasi konsumen API.

1. Endpoint berbahaya masuk ke kode produksi

Contoh terburuk adalah perubahan kecil yang tidak merusak tampilan situs, tetapi mengubah instruksi integrasi.

Misalnya, penyerang mengubah:

https://api.payments.acme.com/v2/charge

menjadi domain yang mereka kendalikan.

Atau mereka mengubah instruksi OAuth sehingga token exchange dikirim ke URL yang salah.

Situs tetap berjalan. YAML tetap valid. CI tetap hijau. Namun, developer berikutnya yang menyalin contoh dari dokumentasi resmi dapat mengirim data produksi ke endpoint yang salah.

Contoh fragmen OpenAPI:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Jika servers.url diubah ke domain penyerang, setiap konsumen yang meregenerasi client dari spesifikasi tersebut dapat mengirim data sensitif ke tempat yang salah. Perubahannya kecil, tetapi dampaknya besar.

2. Endpoint internal ikut bocor

Repositori dokumentasi sering tumbuh tanpa disiplin. Spesifikasi API publik bisa bercampur dengan:

• endpoint internal,
• route admin,
• endpoint debug,
• operasi khusus partner,
• parameter eksperimental.

Jika repositori publik, endpoint tersebut menjadi peta serangan. Jika repositori privat dicuri, seperti dalam skenario pelanggaran repositori internal, penyerang tetap mendapatkan inventaris detail tentang endpoint, parameter, dan payload.

Untuk menemukan celah seperti ini lebih awal, gunakan pendekatan review permukaan API seperti yang dibahas dalam daftar periksa pengujian keamanan API 2026.

3. GitHub Pages publik tidak punya access control

GitHub Pages menyajikan file statis. Untuk API publik, itu cukup. Untuk dokumentasi internal, partner-only, atau customer-only, itu tidak cukup karena tidak ada gerbang akses.

Pola yang sering muncul adalah “security by obscure URL”:

https://docs.example.com/private-v2-partner-api-9832

Ini bukan kontrol akses. URL bisa bocor lewat:

• riwayat browser,
• header referrer,
• log proxy,
• bookmark yang dibagikan,
• chat internal,
• screenshot.

Jika seseorang memiliki URL tersebut, mereka dapat membaca semuanya tanpa autentikasi dan tanpa audit trail yang jelas.

4. Dokumentasi usang menjadi sulit dibedakan dari tampering

Tidak semua kegagalan membutuhkan penyerang. Dokumentasi bisa drift dari API aktual.

Contoh:

1. backend mengubah response field,
2. spesifikasi OpenAPI tidak diperbarui,
3. konsumen mengikuti dokumentasi lama,
4. integrasi gagal,
5. waktu debugging terbuang.

Masalahnya makin buruk saat ada potensi kompromi. Tanpa histori dan integritas yang jelas, Anda tidak bisa menjawab:

• apakah endpoint ini memang selalu salah?
• apakah seseorang baru saja mengubahnya?
• apakah situs live cocok dengan sumber yang direview?

Dokumentasi yang tidak dapat diverifikasi tidak jauh lebih baik daripada tidak ada dokumentasi.

Kapan docs-as-code di Git aman digunakan

Docs-as-code tetap praktik yang valid. Menyimpan OpenAPI dan markdown di Git, membangun Swagger UI atau Redoc, lalu deploy ke static host memberi banyak manfaat:

• pull request review,
• histori perubahan,
• versioning bersama kode,
• proses build yang dapat diotomatisasi.

Pertanyaannya bukan “Git atau bukan Git”, tetapi “apakah setup ini aman untuk jenis API ini?”

Docs-as-code cocok jika

Gunakan docs-as-code di Git jika kondisi berikut terpenuhi:

• API sepenuhnya publik.
• Tidak ada endpoint internal atau partner-only di repositori yang sama.
• Branch protection aktif.
• Perubahan dokumentasi wajib melalui review.
• Akses tulis dibatasi ke orang dan service account yang diaudit.
• CI/CD menggunakan dependency/action yang dipin atau direview.
• Kredensial deployment dibatasi.
• Spesifikasi dihasilkan dari atau divalidasi terhadap API nyata.
• Ada owner yang bertanggung jawab menjaga spesifikasi tetap sinkron.

Dalam kondisi ini, Git memberi transparansi. Pull request menjadi kontrol integritas. Histori commit menjadi audit trail.

Docs-as-code menjadi risiko jika

Setup yang sama menjadi berbahaya jika:

• dokumentasi seharusnya privat, tetapi host tidak punya access control,
• akses tulis terlalu luas,
• commit dokumentasi dianggap “hanya docs” dan jarang direview,
• spesifikasi diedit manual dan drift dari API aktual,
• endpoint internal bercampur dengan endpoint publik,
• tidak ada cara memverifikasi bahwa situs live cocok dengan sumber yang direview,
• token CI atau service account tidak dipantau.

Pelanggaran GitHub mengingatkan bahwa repositori privat tetap bisa bocor jika endpoint developer atau supply chain alat pengembangan disusupi. Git memberi histori dan review, tetapi tidak memberi kerahasiaan jika repositori itu sendiri dicuri.

Untuk perbandingan pendekatan dokumentasi self-hosted, lihat perbandingan dokumen API yang di-host sendiri.

Kesimpulannya: pertahankan docs-as-code jika API Anda publik dan pipeline Anda disiplin. Pertimbangkan lapisan tambahan jika dokumentasi membutuhkan kontrol akses, review docs tidak seketat kode, atau Anda tidak bisa membuktikan bahwa situs live cocok dengan sumber yang direview.

Checklist dokumentasi API yang aman

“Dokumentasi API yang aman” harus bisa diuji. Gunakan empat properti berikut.

1. Kontrol akses

Dokumentasi hanya boleh dibaca oleh audiens yang tepat.

Gunakan kontrol nyata seperti:

• password,
• allowlist IP,
• allowlist email,
• SSO,
• login kustom.

Jangan mengandalkan URL yang sulit ditebak.

Pertanyaan audit:

Bisakah Anda menyebutkan siapa saja yang dapat membaca dokumentasi API saat ini, lalu mencabut akses salah satu dari mereka dalam waktu kurang dari satu menit?

2. Versioning

Setiap versi dokumentasi yang dipublikasikan harus tetap tersedia dan dapat diidentifikasi.

Contoh:

• konsumen API v1 melihat dokumen v1,
• konsumen API v2 melihat dokumen v2,
• tim dapat melihat isi dokumentasi pada tanggal tertentu.

Pertanyaan audit:

Apakah developer yang masih memakai API v1 bisa menemukan dokumentasi v1 yang akurat?

3. Integritas

Anda harus bisa memverifikasi bahwa dokumentasi live adalah dokumentasi yang memang dimaksudkan untuk dipublikasikan.

Pertanyaan audit:

Jika seseorang mengubah satu URL endpoint di dokumentasi live satu jam lalu, apakah sistem Anda akan mendeteksinya?

4. Audit trail

Anda perlu menjawab:

• siapa yang mengubah dokumentasi,
• apa yang diubah,
• kapan perubahan terjadi,
• versi mana yang dipublikasikan.

Pertanyaan audit:

Bisakah Anda menghasilkan log perubahan dokumentasi yang dipublikasikan selama 90 hari terakhir?

Git dapat membantu versioning, integritas, dan audit trail jika branch protection serta review diterapkan. Namun, static hosting seperti GitHub Pages biasanya lemah di kontrol akses. Di sinilah lapisan dokumentasi terkelola menjadi berguna.

Bagaimana Apidog membantu mengamankan dokumentasi API

Apidog adalah platform API untuk mendesain, men-debug, menguji, melakukan mocking, dan mendokumentasikan API. Untuk mencoba alurnya, unduh Apidog, lalu buka proyek dengan definisi API.

Dokumentasi dipublikasikan dari sumber kebenaran yang terkontrol

Di Apidog, dokumentasi dihasilkan dari desain API di dalam proyek. Anda mendesain endpoint, skema, dan autentikasi di desainer visual, lalu Apidog secara otomatis menghasilkan dokumentasi dari definisi tersebut.

Alur praktisnya:

1. Buat atau impor definisi API.
2. Lengkapi endpoint, schema, request body, response, dan auth.
3. Publikasikan dokumentasi.
4. Bagikan situs dokumentasi sesuai aturan akses yang dipilih.

Manfaat integritasnya: dokumentasi bukan markdown terpisah yang mudah drift. Dokumentasi mengikuti definisi API yang dikontrol di dalam proyek.

Kontrol akses dokumentasi

Saat memublikasikan dokumentasi, Anda dapat memilih visibilitas yang sesuai:

• Publik: siapa pun dengan tautan dapat membaca. Cocok untuk API publik.
• Password protection: dokumentasi hanya dapat diakses dengan password.
• Allowlist IP: batasi akses ke IP kantor, VPN, atau range tertentu.
• Allowlist email: hanya email/domain tertentu yang dapat mengakses. Contoh: *@yourcompany.com.
• Login kustom: integrasikan sistem autentikasi sendiri dengan JWT.

Apidog mendokumentasikan metode ini dalam panduan mengontrol akses dokumentasi API.

Dengan pendekatan ini, Anda bisa menjawab pertanyaan audit kontrol akses secara konkret: siapa yang bisa membaca dokumentasi dan bagaimana akses mereka dicabut.

Custom domain

Anda dapat menyajikan dokumentasi di domain sendiri, misalnya:

developer.yourcompany.com

Apidog mendukung custom domain melalui CNAME DNS atau reverse proxy.

Custom domain bukan kontrol keamanan utama, tetapi membantu menjaga dokumentasi tetap berada di permukaan yang dikelola dan dikenali oleh organisasi Anda.

Spesifikasi OpenAPI tetap sinkron

Drift antara dokumentasi dan API aktual adalah risiko keamanan sekaligus risiko operasional.

Apidog memperlakukan desain API sebagai sumber kebenaran dan menjaga dokumentasi tetap sinkron saat desain berubah. Apidog juga mendukung impor OpenAPI 3.0, 3.1, Swagger 2.0, serta impor terjadwal untuk menjaga spesifikasi eksternal tetap terbaru.

Jika saat ini Anda memelihara spesifikasi manual di repositori Git, pertimbangkan untuk menjadikan Apidog sebagai sumber kebenaran agar dokumentasi yang dipublikasikan selalu cocok dengan definisi yang dikontrol. Tim yang beralih dari SwaggerHub dapat mengikuti panduan migrasi dokumen API SwaggerHub ke Apidog.

Versioning dokumentasi

Apidog mendukung versioning dokumentasi sehingga beberapa versi dapat dipublikasikan berdampingan.

Contoh:

• dokumentasi v1 tetap tersedia untuk konsumen lama,
• dokumentasi v2 dapat dipublikasikan untuk integrasi baru,
• perubahan API dan dokumentasi tetap terlacak.

Ini membantu menjawab dua kebutuhan sekaligus: versioning dan audit trail.

Perbandingan opsi hosting dokumentasi

Properti	GitHub Pages Publik (Swagger UI / Redoc)	Dokumen self-hosted di server Anda	Dokumen terkelola (Apidog)
Kontrol akses	Tidak ada; biasanya hanya URL yang tidak jelas	Bergantung pada yang Anda bangun dan pelihara	Bawaan: password, IP, email, login kustom
Versioning	Manual; build atau branch terpisah	Manual	Bawaan; versi dapat dipublikasikan berdampingan
Integritas	Git review + histori, jika diberlakukan	Bergantung pada pipeline	Dokumen dihasilkan dari desain API yang terkontrol
Audit trail	Histori Git untuk repo, bukan selalu untuk deployment	Bergantung pada logging	Riwayat perubahan pada desain dan dokumentasi
Biaya pemeliharaan	Rendah di awal, tetapi pipeline tetap harus dijaga	Tinggi; Anda memiliki seluruh stack	Rendah; platform menangani hosting dan gerbang akses
Paling cocok	API publik dengan pipeline disiplin	Tim dengan kebutuhan self-hosting ketat	Tim yang membutuhkan access control tanpa overhead operasional besar

Tidak ada opsi yang selalu benar. GitHub Pages cocok untuk API publik dengan pipeline yang terkunci. Self-hosting cocok untuk kebutuhan residensi data atau isolasi ketat. Untuk detail trade-off, lihat perbandingan dokumen API yang di-host sendiri dan perbandingan Scalar vs SwaggerHub vs Apidog.

Pilih berdasarkan empat properti keamanan, bukan karena setup lama sudah berjalan sejak tiga tahun lalu.

Kesimpulan

Pelanggaran GitHub bukan alasan untuk meninggalkan docs-as-code atau tidak mempercayai GitHub. Ini adalah pengingat untuk mengaudit permukaan yang sering dilupakan: dokumentasi API.

Langkah praktis berikutnya:

1. Daftar semua tempat dokumentasi API Anda dipublikasikan.
2. Cek setiap tempat terhadap kontrol akses, versioning, integritas, dan audit trail.
3. Pisahkan endpoint internal dari dokumentasi publik.
4. Pastikan perubahan dokumentasi direview seperti perubahan kode.
5. Jika kontrol akses adalah celah terbesar, coba publikasikan satu proyek di Apidog dengan password atau allowlist email untuk melihat bagaimana lapisan terkelola menanganinya.