Kembali ke dokumentasiKonektor

Konektor kustom

Tambahkan konektor kustom dengan kunci API atau kredensial OAuth.

Terakhir diperbarui 10 Juli 2026 · 5 min read

Katalog mencakup 100+ layanan, tetapi setiap tim memiliki beberapa alat internal atau produk SaaS regional yang tidak ada di dalamnya. Konektor kustom menyelesaikan hal itu.

Anda mendaftarkan sebuah kredensial — kunci API atau kredensial OAuth — dan memberi tahu Zero cara memanggil layanan tersebut. Dari sana, Zero memperlakukan konektor kustom Anda secara identik dengan konektor bawaan: log audit yang sama, proksi akses-terbroker yang sama, gerbang tindakan-sensitif yang sama.

Dua varian

Pilih tipe yang sesuai dengan layanan Anda:

  • Kunci API — bekerja untuk layanan apa pun yang mengautentikasi dengan token statis di header. Jalur paling sederhana dan cepat: tempel kunci, beri nama konektor, arahkan Zero ke URL dasar. Sebagian besar API internal dan banyak alat SaaS menggunakan ini.
  • OAuth 2.0 — untuk layanan yang menerbitkan token per pengguna via OAuth. Anda menyediakan client ID dan secret, mengonfigurasi cakupan yang Anda inginkan agar bisa diminta Zero, dan Zero menjalankan tarian OAuth per pengguna saat diperlukan.

Jika Anda tidak yakin mana yang harus digunakan, periksa dokumentasi API layanan upstream. Kata "API key" (atau "personal access token") biasanya berarti varian 1; "OAuth" (atau "client credentials") biasanya berarti varian 2.

Menyiapkan konektor kunci-API

  1. Buka halaman Connectors di ruang kerja Anda.
  2. Klik Add custom connector → API key.
  3. Isi:
    • Name. Sesuatu yang bisa dikenali Zero saat membaca prompt, mis. internal-billing-api atau acme-crm.
    • Base URL. Akar dari API: https://api.internal.acme.com.
    • Auth header. Biasanya Authorization: Bearer YOUR_TOKEN atau X-API-Key: YOUR_TOKEN. Cocokkan dengan yang diharapkan layanan.
    • API key. Tempel kredensial. Disimpan terenkripsi; tidak pernah terlihat setelah disimpan.
    • Allowed paths (opsional). Batasi Zero ke endpoint tertentu, seperti /v1/invoices/*. Mengurangi radius ledakan.
  4. Klik Save dan Test connection. Zero melakukan ping ke URL dasar dengan GET / (atau path yang Anda tentukan) dan melaporkan responsnya.

Menyiapkan konektor OAuth 2.0

Sedikit lebih banyak pekerjaan, tetapi sepadan untuk layanan di mana otorisasi per pengguna penting:

  1. Daftarkan aplikasi OAuth dengan layanan upstream. Anda akan mendapatkan client ID dan client secret. Atur redirect URI ke yang ditampilkan VM0 pada formulir tambah-konektor.
  2. Di VM0: Add custom connector → OAuth 2.0.
  3. Isi:
    • Name dan Base URL, seperti di atas
    • Authorization URL dan Token URL dari dokumentasi OAuth layanan upstream
    • Client ID dan Client secret
    • Scopes. Daftar cakupan yang boleh diminta Zero. Gunakan minimum yang mencakup alur kerja Anda.
  4. Simpan. Sesi pertama yang membutuhkan konektor ini memicu alur OAuth per pengguna.

Memberi tahu Zero cara menggunakan konektor kustom

Dua cara. Pilih mana pun yang sesuai dengan alur kerja Anda.

Gambarkan secara inline saat Anda meminta Zero melakukan sesuatu:

"Gunakan konektor internal-billing-api untuk mengambil faktur #4422. Lalu kirim PDF-nya ke ops@acme.com."

Zero memuat spesifikasi konektor dan menentukan endpoint mana yang harus dipanggil. Ini bekerja karena konektor hadir dengan metadata gaya OpenAPI (ditemukan otomatis untuk banyak layanan, opsional disediakan secara manual).

Tulis sebuah skill yang merujuk konektor berdasarkan nama. Isi skill menggambarkan prosedurnya; Zero memuat skill secara otomatis ketika deskripsinya cocok dengan permintaan yang masuk. Untuk alur kerja berulang, ini lebih rapi daripada menggambarkan ulang secara inline setiap kali.

Sebuah skill bernama pull-invoice dengan deskripsi "ambil faktur dari internal-billing-api dan kirim PDF-nya" — begitu ditulis, Zero memanggilnya kapan pun seseorang meminta faktur.

Spesifikasi OpenAPI dan skema inline

Zero bekerja paling baik dengan konektor kustom ketika ia mengetahui endpoint, metode, dan parameter yang tersedia. Tiga cara untuk menyediakannya:

  • Temukan otomatis dari /openapi.json atau /swagger.json layanan jika ia mengeksposnya. Cukup arahkan Zero ke URL-nya.
  • Unggah spesifikasi. Tempel atau unggah OpenAPI 3 YAML/JSON. Zero mengurainya dan menawarkan metadata gaya tooltip saat menyusun panggilan.
  • Deskripsi inline. Untuk alat internal tanpa spesifikasi, Anda dapat menulis deskripsi markdown singkat di isi konektor — endpoint, metode, contoh payload. Kasar tetapi fungsional.

Tanpa spesifikasi, Zero tetap bekerja — ia hanya harus menebak lebih banyak tentang bentuk parameter. Untuk konektor kustom yang sering digunakan, spesifikasi cepat memberi hasil balik.

Berbagi antar ruang kerja

Konektor kustom bercakupan ruang kerja secara bawaan. Dua tim di organisasi yang sama masing-masing dapat memelihara konektor kustom mereka sendiri untuk API internal yang sama. Untuk organisasi yang menginginkan satu penyiapan kanonik:

  • Konektor tingkat-organisasi enterprise. Tersedia pada paket enterprise. Siapkan sekali di tingkat organisasi; muncul di setiap ruang kerja di bawah organisasi tersebut. Direkomendasikan untuk API internal yang digunakan semua orang.
  • Paket konektor. Untuk organisasi yang sangat besar, tim platform internal dapat menerbitkan konektor kustom sebagai paket berversi; ruang kerja memasangnya dan menerima pembaruan secara otomatis.

Keamanan dan batas laju

  • Kredensial. Terenkripsi saat disimpan dengan kunci per ruang kerja. Tidak pernah terlihat setelah disimpan; hanya dapat dimasukkan ulang.
  • Audit per panggilan. Setiap permintaan melalui konektor kustom muncul di log sesi dengan metode, URL, kode status, dan waktu.
  • Batas laju. Ditegakkan oleh layanan upstream. Zero menangani respons 429 dengan backoff eksponensial hingga batas yang dikonfigurasi ruang kerja.
  • Path yang diizinkan. Opsional: batasi Zero ke pola URL tertentu. Mengurangi radius ledakan jika kunci konektor terlalu diistimewakan.
  • Hanya-baca secara bawaan. Konektor kustom baru ditandai hanya-baca. Memberikan akses tulis memerlukan konfigurasi eksplisit per ruang kerja.

Jebakan umum

  • Kunci API terlalu luas. Jika layanan Anda mendukungnya, buat kunci bercakupan untuk Zero alih-alih menggunakan kembali kunci admin pribadi Anda. Lebih mudah untuk dirotasi dan diaudit.
  • Skema hilang. Tanpa spesifikasi OpenAPI atau deskripsi inline, Zero menebak bentuk parameter. Itu bekerja untuk kasus sederhana dan gagal untuk objek bertingkat. Sediakan spesifikasi bila Anda bisa.
  • URL dasar belum diuji. Selalu klik Test connection setelah penyiapan. 401 atau 404 pada tahap ini jauh lebih baik daripada 401 di sesi kritis.
  • Lupa merotasi. Setel pengingat kalender untuk merotasi kunci setiap kuartal. Rotasi kunci konektor hanya perlu satu klik di VM0; rotasi upstream lah yang memakan sebagian besar waktu.

Berikutnya apa

  • Lihat Skills untuk menangkap alur kerja konektor-kustom yang berulang.
  • Lihat Permissions untuk cara kredensial konektor-kustom ditangani.
  • Lihat Katalog sebelum membangun konektor kustom — layanan Anda mungkin sudah didukung.