REST API Localtonet
Di halaman ini 8 bagian
- Referensi interaktif
- Sebelum memulai
- URL dasar dan autentikasi
- Konvensi
- Kesalahan
- Batas laju
- Contoh
- Daftar tunnel Anda
- Buat tunnel HTTP dengan subdomain acak
- Mulai tunnel
- Grup endpoint
- Tunnel
- Operasi tunnel massal
- Konfigurasi tunnel
- AuthToken
- Grup token
- Server
- Penyedia SSO
- Akses VPN
- Pemecahan masalah
- Halaman terkait
REST API v2 melakukan apa yang dilakukan dasbor untuk tunnel: membuat, memulai, menghentikan, menghapus, dan mengonfigurasinya, serta mengelola AuthToken, grup token, dan penyedia SSO. Anda mengautentikasi setiap permintaan dengan kunci API Anda.
Referensi interaktif #
Setiap endpoint, beserta model permintaan dan responsnya serta formulir untuk mencobanya, ada di referensi interaktif:
- localtonet.com/api: API v2, versi terbaru. Anda juga dapat mengaksesnya dengan tombol UI API di dasbor.
- localtonet.com/api/v1: API v1, dipertahankan untuk integrasi yang sudah ada. Gunakan v2 untuk pekerjaan baru.
Halaman ini memberi Anda konvensi dan gambaran umum grup endpoint. Untuk kolom persis dari sebuah permintaan, buka endpoint tersebut di referensi.
Sebelum memulai #
- Kunci API Anda. Buka Dasbor dan gunakan Salin pada kartu Kunci API. Lihat Akun dan keamanan.
- Untuk membuat tunnel: AuthToken perangkat yang akan menjalankan tunnel, dan klien Localtonet yang terhubung dengan token tersebut. Lihat AuthToken.
Jaga kerahasiaan kunci API Anda. Siapa pun yang memilikinya dapat membuat, mengubah, dan menghapus tunnel serta token Anda. Ubah pada kartu Kunci API membuat kunci baru dan membatalkan kunci lama.
URL dasar dan autentikasi #
Semua endpoint v2 diawali dengan:
https://localtonet.com/api/v2Kirim kunci API sebagai Bearer token di header Authorization pada setiap permintaan:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>Kunci API yang disalin di dasbor tim mencantumkan AuthToken dan tunnel Anda di tim tersebut; kunci akun Anda sendiri mencantumkan AuthToken yang tidak termasuk tim mana pun.
Konvensi #
| Topik | Perilaku API |
|---|---|
| Format | Body permintaan dan respons berupa JSON. Kirim Content-Type: application/json bersama body. |
| ID tunnel | tunnelId dalam path adalah id numerik tunnel, seperti yang dikembalikan endpoint daftar dan pembuatan. |
| AuthToken dalam path | {token} adalah string AuthToken itu sendiri. |
| Kode sukses | 200 dengan body untuk pembacaan, 201 untuk sebagian besar pembuatan (endpoint pembuatan tunnel mengembalikan tunnel baru), 204 tanpa body untuk sebagian besar aksi dan pembaruan. Referensi menunjukkan jawaban setiap endpoint. |
| Endpoint massal | Path yang berisi /bulk/ menerima array JSON dan hingga 100 item per permintaan (/tunnels/bulk/protocol-type: hingga 500). |
| Tunnel baru | Tunnel yang Anda buat belum berjalan. Mulai dengan aksi start. Hanya endpoint proxy/with-detail yang dapat memulai tunnel dalam panggilan yang sama, dengan isStartAfterCreate. |
Kesalahan #
| Status | Arti | Body |
|---|---|---|
400 | Body permintaan tidak valid, atau operasi ditolak, misalnya karena batas paket Anda. | Untuk sebagian besar endpoint berupa objek masalah dalam JSON; title berisi pesan. Kesalahan validasi dan kesalahan endpoint massal tercantum di bawah errors. |
401 | Kunci API tidak ada atau tidak valid. | Tidak ada pesan khusus |
403, 409 | Dikembalikan oleh beberapa endpoint konfigurasi tunnel dan akses VPN ketika perubahan tidak diizinkan atau bertentangan dengan konfigurasi saat ini. | Objek masalah dengan pesan di title. |
404 | Tunnel atau objek tidak ditemukan atau bukan milik Anda. | Kosong atau objek masalah |
429 | Terlalu banyak permintaan. | Lihat batas laju di bawah. |
Batas laju #
Permintaan dibatasi lajunya. Permintaan yang melebihi batas dijawab dengan 429 Too Many Requests. Tunggu lalu kirim lagi; gunakan endpoint massal alih-alih banyak panggilan tunggal.
Contoh #
Ganti <YOUR_API_KEY> dengan kunci API Anda dan <YOUR_TOKEN> dengan AuthToken perangkat.
Daftar tunnel Anda #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"Jawabannya berupa array JSON dengan satu objek per tunnel. Kolomnya antara lain id, title, url (alamat publik), protocolType, authToken, serverId, clientIp dan clientPort (target lokal), status, dan connectionStatus. Jika Anda belum punya tunnel, jawabannya 404, bukan array kosong.
Buat tunnel HTTP dengan subdomain acak #
Pertama ambil kode server yang ingin Anda gunakan:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Setiap entri memiliki serverCode, serverName, dan serverDomain. Lalu buat tunnel. Contoh ini meneruskan ke aplikasi web di port 3000 perangkat:
curl -X POST https://localtonet.com/api/v2/tunnels/http/random-subdomain \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"authToken": "<YOUR_TOKEN>",
"serverCode": "<SERVER_CODE>",
"protocolType": 1,
"ip": "127.0.0.1",
"port": 3000
}'| Kolom | Arti | Nilai |
|---|---|---|
authToken | AuthToken perangkat yang menjalankan tunnel. | Wajib |
serverCode | Server, dari GET /servers. | Wajib |
protocolType | Jenis tunnel. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | Alamat IP lokal tujuan penerusan tunnel. | Alamat IP yang valid, misalnya 127.0.0.1 |
port | Port lokal. | 1 sampai 65534 |
path | Folder lokal yang akan dibagikan. | Wajib hanya untuk File Server |
Jawabannya 201 Created dengan tunnel baru. Catat id dan url-nya.
Mulai tunnel #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"Jawabannya 204 No Content. Tunnel dapat dijangkau di url-nya saat klien perangkat terhubung. Hentikan lagi dengan /actions/stop.
Grup endpoint #
Semua path di bawah ini relatif terhadap https://localtonet.com/api/v2.
Tunnel #
| Metode | Path | Tujuan |
|---|---|---|
| GET | /tunnels | Mencantumkan semua tunnel Anda. |
| GET | /tunnels/{tunnelId} | Mengambil satu tunnel. |
| POST | /tunnels/http/random-subdomain | Membuat tunnel HTTP, File Server, atau MCP Gateway dengan subdomain acak. |
| POST | /tunnels/http/custom-subdomain | Membuat satu dengan subdomain pilihan Anda. |
| POST | /tunnels/http/custom-domain | Membuat satu di domain Anda sendiri. |
| POST | /tunnels/tcp-udp | Membuat tunnel TCP, UDP, atau gabungan TCP dan UDP. |
| POST | /tunnels/proxy | Membuat tunnel proxy HTTP, SOCKS5, Shadowsocks, atau VLESS. |
| POST | /tunnels/proxy/with-detail | Membuat tunnel proxy dan mengembalikan detail koneksi lengkapnya. |
| POST | /tunnels/shared-proxy | Membuat tunnel proxy bersama (rotasi). |
| POST | /tunnels/{tunnelId}/actions/start | Memulai tunnel. |
| POST | /tunnels/{tunnelId}/actions/stop | Menghentikan tunnel. |
| DELETE | /tunnels/{tunnelId} | Menghapus tunnel secara permanen. |
| PATCH | /tunnels/{tunnelId}/title | Mengubah judul. |
| PATCH | /tunnels/{tunnelId}/local-ip | Mengubah alamat IP lokal. |
| PATCH | /tunnels/{tunnelId}/local-port | Mengubah port lokal. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Mengaktifkan atau menonaktifkan reservasi port tunnel TCP/UDP. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Mengaktifkan atau menonaktifkan mode koneksi lama. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Mengubah protokol proxy dari tunnel proxy. |
| GET | /tunnels/{tunnelId}/request-logs | Log permintaan HTTP terbaru dari tunnel HTTP atau File Server. |
Operasi tunnel massal #
| Metode | Path | Tujuan |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Membuat beberapa tunnel HTTP dengan subdomain acak. |
| POST | /tunnels/bulk/http/custom-subdomain | Membuat beberapa dengan subdomain kustom. |
| POST | /tunnels/bulk/http/custom-domain | Membuat beberapa di domain kustom. |
| POST | /tunnels/bulk/tcp-udp | Membuat beberapa tunnel TCP/UDP. |
| POST | /tunnels/bulk/proxy | Membuat beberapa tunnel proxy. |
| POST | /tunnels/bulk/proxy/with-detail | Membuat beberapa tunnel proxy dan mengembalikan detail koneksinya. |
| POST | /tunnels/bulk/shared-proxy | Membuat beberapa tunnel proxy bersama (rotasi). |
| POST | /tunnels/bulk/actions/start | Memulai beberapa tunnel. Body: array ID tunnel, misalnya [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Menghentikan beberapa tunnel. Body: array ID tunnel. |
| DELETE | /tunnels/bulk | Menghapus beberapa tunnel. Body: array ID tunnel. |
| PATCH | /tunnels/bulk/protocol-type | Mengubah protokol proxy dari beberapa tunnel proxy. |
Konfigurasi tunnel #
Endpoint ini mengubah pengaturan satu tunnel. Semuanya diawali dengan /tunnels/{tunnelId}. Fungsi setiap pengaturan dijelaskan di Referensi pengaturan.
| Metode | Path setelah /tunnels/{tunnelId} | Tujuan |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Mencantumkan, menambah, mengatur mode izinkan atau tolak, atau menghapus semua pembatasan IP. Hapus satu dengan /ip-restrictions/{restrictionId}. |
| GET, POST, PATCH, DELETE | /access-controls | Hal yang sama untuk kontrol akses path URL. Hapus satu dengan /access-controls/{controlId}. |
| GET, PATCH | /headers | Header HTTP kustom. |
| GET, PATCH | /authentication | Autentikasi Dasar HTTP. |
| GET, PATCH | /expiration | Tanggal kedaluwarsa tunnel. |
| GET, PATCH | /server-port | Port sisi server dari tunnel TCP/UDP. |
| GET, PATCH | /http-timeout | Batas waktu permintaan HTTP. |
| GET, PATCH | /rate-limit | Batas kecepatan. |
| GET, PATCH | /bandwidth-limit | Batas total transfer data. |
| GET | /bandwidth-usage | Penggunaan bandwidth saat ini. Atur ulang penghitung dengan POST /bandwidth-usage/reset. |
| GET, PATCH | /arguments | Argumen baris perintah kustom untuk tunnel. |
| GET, POST | /shared-proxy-clients | Mencantumkan atau menambah klien tunnel proxy bersama (rotasi). Perbarui atau hapus satu dengan PATCH atau DELETE /shared-proxy-clients/{clientId}. |
| GET | /advanced-settings | Semua pengaturan lanjutan tunnel dalam satu jawaban. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Membaca atau mengganti satu pengaturan lanjutan. |
| PATCH | /ssl-stream | Mengganti pengaturan SSL stream. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Membaca atau mengubah satu nilai. |
| GET, PUT | /token-groups | Grup token yang ditetapkan ke tunnel. |
| GET, PATCH | /server | Server tunnel. |
AuthToken #
| Metode | Path | Tujuan |
|---|---|---|
| GET | /auth-tokens | Mencantumkan AuthToken Anda. |
| GET | /auth-tokens/detail | Mencantumkan AuthToken Anda beserta detailnya. |
| GET | /auth-tokens/{token} | Detail satu AuthToken. |
| POST | /auth-tokens | Membuat AuthToken. |
| DELETE | /auth-tokens/{token} | Menghapus AuthToken. |
| GET | /auth-tokens/{token}/tunnels | Tunnel milik sebuah AuthToken. |
| GET | /auth-tokens/{token}/ip-history | Riwayat perubahan alamat IP publik perangkat. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Pengaturan otomatisasi mode pesawat. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Menambah tautan change-IP. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Menghapus tautan change-IP. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Menambah tautan restart perangkat. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Menghapus tautan restart perangkat. |
| GET, PATCH | /auth-tokens/{token}/arguments | Argumen klien yang disimpan pada AuthToken. |
Grup token #
| Metode | Path | Tujuan |
|---|---|---|
| GET | /token-groups | Mencantumkan grup token Anda. |
| GET | /token-groups/{id} | Mengambil satu grup token. |
| POST | /token-groups | Membuat grup token. |
| DELETE | /token-groups/{id} | Menghapus grup token. |
| POST | /token-groups/{id}/auth-tokens | Menambahkan AuthToken ke grup. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Menghapus AuthToken dari grup. |
Server #
| Metode | Path | Tujuan |
|---|---|---|
| GET | /servers | Mencantumkan server tempat Anda dapat membuat tunnel, beserta serverCode yang dipakai pada permintaan pembuatan. |
Penyedia SSO #
| Metode | Path | Tujuan |
|---|---|---|
| GET | /sso-providers | Mencantumkan penyedia SSO Anda. |
| GET | /sso-providers/default-endpoints | Endpoint default untuk satu jenis penyedia SSO. |
| POST | /sso-providers | Membuat atau memperbarui penyedia SSO. |
| DELETE | /sso-providers/{id} | Menghapus penyedia SSO. |
| GET | /sso-providers/tunnel/{tunnelId} | Penyedia SSO yang dikonfigurasi untuk sebuah tunnel. Di sini tunnelId adalah GUID tunnel (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Menyimpan penyedia SSO sebuah tunnel. |
Lihat Single Sign-On untuk fungsi para penyedia.
Akses VPN #
Akses VPN memberikan profil perangkat WireGuard atau OpenVPN pada tunnel proxy; seluruh lalu lintas perangkat tersebut keluar melalui proxy. Endpoint ini diawali dengan /tunnels/{tunnelId}/vpn-access.
| Metode | Path setelah /tunnels/{tunnelId}/vpn-access | Tujuan |
|---|---|---|
| GET | (tidak ada) | Mencantumkan perangkat VPN tunnel. |
| POST | (tidak ada) | Membuat perangkat VPN. |
| DELETE | /{peerId} | Menghapus (mencabut) perangkat VPN. |
| POST | /{peerId}/regenerate | Membuat ulang kunci perangkat VPN. |
| GET | /{peerId}/config | Mengunduh file konfigurasi perangkat VPN. |
| GET | /{peerId}/qr | Kode QR konfigurasi perangkat WireGuard. |
| GET | /{peerId}/credentials | Nama pengguna dan kata sandi perangkat OpenVPN. |
Pemecahan masalah #
Setiap permintaan mengembalikan 401
Periksa header: harus Authorization: Bearer diikuti spasi dan kunci, tanpa tanda kutip di sekitar kunci. Jika Anda memilih Ubah pada kartu Kunci API, kunci lama tidak berfungsi lagi; salin yang baru.
Saya tidak melihat AuthToken tim saya
Anda memakai kunci API akun Anda sendiri. Beralih ke dasbor tim dan salin kunci API di sana.
Tunnel sudah dibuat tetapi alamatnya tidak merespons
Tunnel baru dalam keadaan berhenti. Panggil POST /tunnels/{tunnelId}/actions/start, dan pastikan klien Localtonet perangkat berjalan dengan AuthToken yang Anda gunakan.
Saya mendapat 429 Too Many Requests
Permintaan dibatasi lajunya. Tunggu, lalu kirim permintaan lagi, dan ganti perulangan panggilan tunggal dengan satu permintaan massal.