Cara Otentikasi Apidog CLI: Login, Token, dan Rahasia CI

Pertama kali Anda menjalankan apidog run dan berhenti dengan pesan "No access token found" (Token akses tidak ditemukan), Anda mengalami satu bagian dari alur kerja baris perintah yang tidak ada yang memperingatkan Anda. Flag, ID skenario, reporter semuanya mudah disalin dari tab. Otentikasi adalah langkah di mana perintah yang disalin rusak di mesin Anda, membocorkan rahasia ke log, atau diam-diam berfungsi di laptop Anda dan gagal di CI karena alasan yang tidak dijelaskan oleh pesan kesalahan.

Panduan ini adalah jawaban khusus untuk langkah itu. CLI Apidog adalah paket npm, apidog-cli, yang menjalankan skenario pengujian API yang Anda bangun di aplikasi Apidog langsung dari terminal. Karena skenario tersebut ada di akun Anda, CLI harus membuktikan bahwa ia diizinkan untuk mengambil dan menjalankannya, dan itu dilakukan dengan token akses. Tangani token dengan benar sekali dan setiap eksekusi sesudahnya adalah satu baris perintah yang bersih. Salah menanganinya dan Anda akan menghadapi kesalahan otentikasi yang sama di tiga lingkungan yang berbeda.

Kita akan membahas seluruhnya: membuat token akses, masuk dengan apidog login, memeriksa sebagai siapa Anda masuk dengan apidog whoami, di mana token disimpan, bagaimana apidog run memutuskan token mana yang akan digunakan, dan bagian yang paling sering salah dilakukan tim, yaitu menangani token tersebut sebagai rahasia di CI daripada menempelkannya ke file pipeline. Mekanisme instalasi ada di panduan terpisah; yang ini hanya tentang otentikasi. Jika Anda belum menginstal CLI, mulailah dengan panduan instalasi Apidog CLI, lalu kembali ke sini.

Mengapa CLI membutuhkan token sama sekali

CLI tidak membawa tesnya sendiri. Ia mengakses proyek Apidog Anda, menemukan skenario berdasarkan ID, dan menjalankannya dengan cara yang sama seperti aplikasi desktop. Desain itulah alasan mengapa ia perlu otentikasi: skenario, nilai lingkungan, pernyataan semuanya berada di sisi server di akun Anda, jadi pelari harus mengidentifikasi dirinya sebelum server menyerahkan semua itu.

Token akses adalah cara ia mengidentifikasi dirinya. Token tersebut terikat pada akun Apidog Anda, sehingga eksekusi yang diautentikasi dengan token Anda dapat melakukan apa yang dapat Anda lakukan: membaca proyek Anda, mengambil skenario Anda, melaksanakannya terhadap lingkungan yang telah Anda definisikan. Itulah juga mengapa token adalah kredensial yang Anda jaga. Siapa pun yang memegangnya dapat menjalankan skenario atas nama Anda, terhadap lingkungan apa pun yang menjadi target skenario tersebut. Perlakukan seperti Anda memperlakukan token akses pribadi untuk layanan lainnya.

Ini adalah jenis otentikasi yang berbeda dari otentikasi yang dilakukan oleh pengujian Anda. Skenario Anda mungkin mengirimkan token bearer atau kunci API sendiri ke endpoint yang diuji, dan itu adalah masalah terpisah yang dibahas dalam metode otentikasi API. Token akses CLI mengautentikasi pelari ke Apidog. Kredensial di dalam permintaan Anda mengautentikasi permintaan Anda ke API Anda. Pisahkan keduanya, karena keduanya berada di tempat yang berbeda dan berotasi pada jadwal yang berbeda.

Langkah 1: buat token akses

Anda membuat token di Apidog, bukan dari CLI. Ada dua tempat munculnya, dan yang mana yang Anda gunakan tergantung pada apa yang Anda lakukan.

Untuk token yang terlingkup ke akun Anda yang akan Anda gunakan kembali di berbagai skenario, buka aplikasi Apidog atau konsol web, klik avatar Anda, dan cari bagian token akses API di bawah pengaturan akun Anda.

Buat satu, salin segera, dan simpan di tempat yang aman seperti pengelola kata sandi. Anda biasanya tidak dapat melihat seluruh string lagi setelah Anda meninggalkan halaman, yang normal untuk kredensial dan alasan untuk menyalinnya segera setelah muncul.

Untuk token yang terikat pada skenario tertentu yang Anda hubungkan ke CI, ada jalur yang lebih cepat. Buka skenario pengujian, beralih ke tab CI/CD-nya, pilih opsi baris perintah, dan klik untuk membuat token akses. Apidog membangun seluruh perintah apidog run untuk Anda dengan token, ID skenario, dan ID lingkungan yang sudah terisi. Perintah yang dihasilkan itu adalah titik awal kanonis, dan menyalinnya berarti Anda tidak perlu mengetik ID secara manual. Panduan CLI Apidog lengkap membahas tab CI/CD itu secara rinci.

Bagaimanapun, hasilnya sama: sebuah string token. Apa yang Anda lakukan selanjutnya adalah pilihan antara dua gaya otentikasi.

Langkah 2: pilih gaya otentikasi Anda

CLI mendukung dua cara untuk menyajikan token, dan keduanya cocok untuk situasi yang berbeda.

Yang pertama adalah login yang disimpan. Anda menjalankan apidog login sekali, CLI menyimpan token ke mesin Anda, dan setiap apidog run berikutnya membacanya secara otomatis. Tidak ada token di baris perintah setelah itu. Inilah yang Anda inginkan di mesin pengembang yang Anda gunakan setiap hari.

Yang kedua adalah per-perintah. Anda meneruskan --access-token pada panggilan apidog run itu sendiri, biasanya dari variabel lingkungan. Tidak ada yang disimpan, token disediakan baru setiap kali, dan tidak meninggalkan jejak di disk. Inilah yang Anda inginkan di CI, di mana pelari bersifat sementara dan token berasal dari rahasia.

Anda kemungkinan akan menggunakan keduanya, login yang disimpan secara lokal dan per-perintah di pipeline. Dua bagian berikutnya membahas masing-masing.

Di mesin Anda sendiri, masuk sekali dan lupakan tentang token. Formulir interaktif meminta Anda untuk itu sehingga string tidak pernah muncul di riwayat shell Anda:

apidog login

CLI meminta token akses Anda, Anda menempelkannya, dan menekan Enter. Di balik layar, ia memvalidasi token terhadap Apidog sebelum menyimpan apa pun; token yang tidak valid atau kedaluwarsa ditolak di tempat daripada gagal nanti pada eksekusi pertama Anda. Setelah berhasil, ia mengonfirmasi akun yang digunakan untuk login dan memberi tahu Anda di mana kredensial tersebut disimpan.

Jika Anda lebih suka meneruskan token secara langsung, misalnya di dalam skrip setup, gunakan flag --with-token:

apidog login --with-token YOUR_ACCESS_TOKEN

Satu peringatan dengan bentuk ini: token di baris perintah akan masuk ke riwayat shell Anda dan dapat dibaca dari daftar proses saat perintah berjalan. Lebih disukai menggunakan apidog login interaktif untuk penggunaan langsung, dan --with-token dicadangkan untuk setup non-interaktif di mana Anda membaca nilai dari variabel yang Anda kendalikan. Jangan pernah memasukkan token sungguhan ke dalam skrip yang Anda commit.

Ke mana token pergi? CLI menuliskannya ke file konfigurasi di bawah direktori .apidog di folder home Anda. Itu adalah penyimpanan kredensial lokal di mesin Anda sendiri, yang justru intinya: token berada di disk di mana hanya akun pengguna Anda yang dapat membacanya, dan CLI mengambilnya pada setiap eksekusi berikutnya tanpa Anda perlu mengetiknya lagi. Jika Anda berada di mesin bersama atau mesin sekali pakai, lewati login yang disimpan dan gunakan token per-perintah sebagai gantinya, sehingga tidak ada yang tersimpan setelah Anda pergi.

Langkah 4: verifikasi dengan apidog whoami

Setelah masuk, konfirmasikan bahwa itu berfungsi sebelum Anda bergantung padanya:

apidog whoami

Ini mencetak akun tempat CLI saat ini diautentikasi. Ini adalah cara tercepat untuk menjawab "apakah saya sudah masuk, dan sebagai siapa?" tanpa menjalankan skenario nyata. Gunakan kapan pun sebuah eksekusi gagal dengan kesalahan otentikasi dan Anda tidak yakin apakah masalahnya adalah token atau sesuatu yang di hilir; jika whoami menampilkan akun Anda, login yang disimpan baik-baik saja dan Anda dapat mencari di tempat lain.

apidog whoami juga menerima --access-token jika Anda ingin memeriksa token tertentu daripada yang disimpan. Itu berguna untuk mengonfirmasi bahwa token CI valid sebelum Anda mempercayainya dalam pipeline: tempelkan token ke dalam apidog whoami --access-token YOUR_ACCESS_TOKEN sekali pakai dari terminal yang aman, lihat akun siapa yang diresolusi, lalu pindahkan ke penyimpanan rahasia Anda.

Saat Anda selesai di mesin bersama, atau saat Anda ingin beralih ke akun lain, bersihkan kredensial yang tersimpan:

apidog logout

Itu menghapus token yang disimpan dari file konfigurasi. apidog run berikutnya akan membutuhkan login baru atau flag --access-token, yang merupakan perilaku yang Anda inginkan setelah mengembalikan mesin.

Langkah 5: bagaimana apidog run memilih token

Setelah Anda memahami urutan pemeriksaan oleh pelari, kesalahan "No access token found" berhenti menjadi misterius. Ketika Anda memanggil apidog run, CLI mencari token dalam urutan ini:

Flag --access-token yang diteruskan pada perintah, jika ada.
Token yang disimpan di disk dari apidog login sebelumnya.

Jika tidak menemukan keduanya, ia berhenti dan memberi tahu Anda untuk menjalankan login terlebih dahulu atau meneruskan --access-token. Prioritas itu berguna: sebuah flag selalu mengalahkan login yang disimpan, sehingga Anda dapat tetap masuk sebagai diri Anda setiap hari dan masih dapat menimpa dengan token yang berbeda untuk eksekusi sekali pakai tanpa harus logout.

Dalam praktiknya ini berarti eksekusi lokal Anda bisa sesingkat ID:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Tidak ada token di baris itu, karena login yang tersimpan menyediakannya. -t menamai skenario berdasarkan ID, -e memilih lingkungan, -n 1 menjalankannya sekali, dan -r cli mencetak laporan yang dapat dibaca. Bandingkan itu dengan bentuk CI, di mana Anda meneruskan token secara eksplisit karena tidak ada yang disimpan:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Perintah yang sama, skenario yang sama, sumber otentikasi yang berbeda. Itulah seluruh perbedaan antara otentikasi lokal dan CI, dan sisa panduan ini adalah tentang mendapatkan bagian CI yang benar. Untuk referensi flag lengkap di balik eksekusi ini, panduan CLI Apidog lengkap mencakup setiap opsi.

Langkah 6: tangani token sebagai rahasia di CI

Di sinilah tim sering mengalami masalah. Solusinya adalah satu aturan: token berada di penyimpanan rahasia sistem CI Anda, dan ia mencapai perintah sebagai variabel lingkungan. Token tersebut tidak pernah muncul di file yang di-commit, definisi pipeline yang diperiksa ke repo, atau log build.

Jangan masuk di dalam CI, dan jangan menulis token ke dalam file yang dibuat oleh runner. Gunakan bentuk --access-token per-perintah, yang diambil dari rahasia yang disamarkan. Setiap contoh di bawah ini mengikuti bentuk yang sama, rahasia diberi nama sekali di platform, direferensikan sebagai $APIDOG_ACCESS_TOKEN di langkah eksekusi.

GitHub Actions

Simpan token di bawah Pengaturan repositori, di Rahasia dan variabel, lalu paparkan ke langkah melalui env:

- name: Run API test scenario
  run: |
    apidog run \
      --access-token "$APIDOG_ACCESS_TOKEN" \
      -t 605067 \
      -e 1629989 \
      -r junit,cli
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub menyamarkan rahasia di log secara otomatis, dan meneruskannya melalui env menjauhkannya dari baris perintah yang terlihat. Kegagalan yang paling umum di sini adalah ketidaksesuaian nama: kunci env, referensi ${{ secrets.X }}, dan rahasia yang Anda buat di Pengaturan semuanya harus menggunakan nama yang sama. Alur kerja lengkap, termasuk artefak laporan, ada di Apidog CLI di GitHub Actions.

GitLab CI

Simpan APIDOG_ACCESS_TOKEN sebagai variabel CI/CD yang disamarkan dan dilindungi di bawah Pengaturan, jangan pernah di file .gitlab-ci.yml. Kemudian referensikan langsung, karena GitLab menyuntikkan variabel proyek ke lingkungan job:

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Menandai variabel "masked" memberi tahu GitLab untuk menghapusnya dari log job; menandainya "protected" menjaganya agar tidak terpakai di cabang yang tidak dilindungi, sehingga fork atau cabang fitur tidak dapat mengeksfiltrasi.

Jenkins

Simpan token sebagai kredensial Jenkins, lalu ikat di blok environment agar tersedia sebagai variabel tanpa pernah dicetak:

pipeline {
  agent any
  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }
  stages {
    stage('API tests') {
      steps {
        sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
      }
    }
  }
}

Jenkins menyamarkan kredensial yang terikat dengan cara ini di output konsol. Jika Anda membangun pipeline lengkap di sekitar langkah ini, Apidog CLI dalam pipeline CI/CD membahas struktur di sekitarnya.

Polanya identik di setiap runner: rahasia yang disamarkan di platform, variabel lingkungan di perintah, dan flag --access-token yang membacanya. Itu adalah disiplin yang sama yang akan Anda terapkan pada kredensial apa pun dalam pipeline, dan layak membaca praktik terbaik manajemen kunci API jika Anda mengelola lebih dari satu.

Memutar dan mencabut token

Token tidak selamanya. Rotasi mereka sesuai jadwal dan cabut saat salah satu mungkin bocor.

Untuk rotasi, buat token baru di Apidog, perbarui rahasia di setiap sistem CI yang menggunakannya, dan jalankan pipeline untuk mengonfirmasi bahwa yang baru berfungsi. Kemudian cabut token lama dari tempat yang sama Anda membuatnya. Secara lokal, jalankan apidog logout diikuti oleh apidog login dengan token baru. Urutan itu penting: perbarui CI sebelum Anda mencabut, atau Anda akan gagal dalam build di antara kedua langkah tersebut.

Cabut segera jika token muncul di tempat yang tidak seharusnya, log, tangkapan layar, commit, terminal bersama. Pencabutan akan membatalkan token di mana pun secara bersamaan, sehingga pipeline apa pun yang masih menggunakan nilai lama akan gagal secara keras, yang merupakan sinyal yang Anda inginkan. Build yang gagal dapat dipulihkan; kredensial langsung di log publik tidak. Untuk kebiasaan yang lebih luas, praktik terbaik rotasi kunci API membahas frekuensinya.

Satu jebakan yang halus: membuat ulang token di Apidog akan membatalkan token sebelumnya. Jika Anda membuat ulang dan lupa memperbarui rahasia CI, pipeline tersebut mulai gagal dengan kesalahan otentikasi meskipun tidak ada perubahan dalam YAML. Ketika build yang biasanya berhasil tiba-tiba tidak dapat melakukan otentikasi dan Anda tidak menyentuh file alur kerja, token yang dibuat ulang adalah hal pertama yang harus diperiksa.

Ketika otentikasi gagal

Kesalahan otentikasi mengelompok menjadi beberapa penyebab. Berikut cara membedakannya.

“Token akses tidak ditemukan.” CLI tidak menemukan flag --access-token maupun login yang tersimpan. Secara lokal, jalankan apidog login. Di CI, konfirmasikan bahwa rahasia terisi dan flag --access-token membacanya; variabel lingkungan kosong menghasilkan pesan yang sama ini.

“Token akses tidak valid” atau kesalahan otentikasi di tengah eksekusi. Token salah, kedaluwarsa, atau dicabut. Jalankan apidog whoami untuk memeriksa token yang disimpan, atau apidog whoami --access-token YOUR_TOKEN untuk memeriksa token tertentu. Jika tidak ada yang merujuk ke akun Anda, buat token baru dan masuk lagi.

Berfungsi secara lokal, gagal di CI. Ketidaksesuaian klasik. Mesin Anda memiliki login yang tersimpan, sehingga eksekusi lokal berhasil; runner CI tidak memiliki apa pun yang tersimpan dan sepenuhnya bergantung pada rahasia. Konfirmasikan bahwa nama rahasia cocok persis di seluruh pengaturan platform dan perintah, dan bahwa nilai disimpan tanpa spasi atau baris baru di akhir, yang mudah terjadi saat menempel.

“Akses ditolak” pada skenario tertentu. Token valid tetapi akun di baliknya tidak dapat menjangkau proyek tersebut. Periksa ID proyek dan skenario, dan konfirmasikan bahwa akun token memiliki akses ke proyek tersebut. Ini adalah masalah otorisasi, bukan otentikasi; CLI membuktikan siapa dirinya, server hanya tidak akan membiarkan akun itu menjalankan skenario tersebut.

Token mencapai perintah tetapi build masih membocorkannya. Jika Anda pernah melihat token mentah di log, Anda mengulanginya di suatu tempat, seringkali baris debug yang mencetak perintah lengkap atau lingkungan. Sembunyikan: cetak panjang token untuk mengonfirmasi bahwa itu terisi, jangan pernah nilainya. Sebagian besar platform CI secara otomatis menyunting rahasia yang diketahui, tetapi echo seluruh perintah yang dibuat secara manual dapat mengalahkan itu.

Di mana otentikasi sesuai dalam alur kerja yang lebih besar

Otentikasi adalah gerbang kecil, sekali pakai yang memungkinkan segala sesuatu di hilir menjadi mungkin. Setelah CLI dapat membuktikan siapa dirinya, menjalankan skenario Apidog menjadi satu perintah, secara lokal di dalam siklus edit-test Anda, di CI pada setiap push, dan bahkan di dalam agen pengkodean AI yang menjalankan pengujian Anda untuk Anda. Pola terakhir itu layak dilihat jika Anda bekerja dengan agen: cara menggunakan agen AI untuk pengujian API menunjukkan bagaimana CLI yang sudah login memungkinkan agen menjalankan skenario Anda dan membaca hasilnya, dan server Apidog MCP menghubungkan spesifikasi Anda langsung ke agen-agen tersebut.

Model mentalnya sederhana. Masuk sekali di mesin Anda dengan apidog login, verifikasi dengan apidog whoami, dan biarkan token yang disimpan menjalankan setiap eksekusi berikutnya. Di CI, lewati login, simpan token dalam rahasia yang disamarkan, dan teruskan per-perintah dengan --access-token. Rotasi sesuai jadwal, cabut jika ada kecurigaan, dan perbarui CI sebelum Anda mencabut. Itulah seluruh cerita otentikasi, dan dengan ini ditangani, CLI memudar ke latar belakang tempat runner pengujian yang baik seharusnya berada.

Anda terus membuat skenario secara visual di Apidog, dan CLI menjalankannya di mana pun tidak ada manusia yang mengawasinya. Unduh Apidog untuk menyiapkan skenario pertama Anda, lalu arahkan runner ke sana. Untuk semua yang dapat dilakukan runner setelah diautentikasi, panduan CLI Apidog lengkap adalah referensi yang harus Anda pegang.

tombol