Langsung ke konten
Localtonet Localtonet Dasbor

REST API Localtonet

Bantuan untuk halaman ini
Di halaman ini 8 bagian
  1. Referensi interaktif
  2. Sebelum memulai
  3. URL dasar dan autentikasi
  4. Konvensi
  5. Kesalahan
  6. Batas laju
  7. Contoh
  8. Daftar tunnel Anda
  9. Buat tunnel HTTP dengan subdomain acak
  10. Mulai tunnel
  11. Grup endpoint
  12. Tunnel
  13. Operasi tunnel massal
  14. Konfigurasi tunnel
  15. AuthToken
  16. Grup token
  17. Server
  18. Penyedia SSO
  19. Akses VPN
  20. Pemecahan masalah
  21. 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:

URL dasar
https://localtonet.com/api/v2

Kirim kunci API sebagai Bearer token di header Authorization pada setiap permintaan:

HTTP
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 #

TopikPerilaku API
FormatBody permintaan dan respons berupa JSON. Kirim Content-Type: application/json bersama body.
ID tunneltunnelId dalam path adalah id numerik tunnel, seperti yang dikembalikan endpoint daftar dan pembuatan.
AuthToken dalam path{token} adalah string AuthToken itu sendiri.
Kode sukses200 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 massalPath yang berisi /bulk/ menerima array JSON dan hingga 100 item per permintaan (/tunnels/bulk/protocol-type: hingga 500).
Tunnel baruTunnel 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 #

StatusArtiBody
400Body 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.
401Kunci API tidak ada atau tidak valid.Tidak ada pesan khusus
403, 409Dikembalikan oleh beberapa endpoint konfigurasi tunnel dan akses VPN ketika perubahan tidak diizinkan atau bertentangan dengan konfigurasi saat ini.Objek masalah dengan pesan di title.
404Tunnel atau objek tidak ditemukan atau bukan milik Anda.Kosong atau objek masalah
429Terlalu 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 #

Bash
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:

Bash
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:

Bash
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
  }'
KolomArtiNilai
authTokenAuthToken perangkat yang menjalankan tunnel.Wajib
serverCodeServer, dari GET /servers.Wajib
protocolTypeJenis tunnel.1 HTTP, 5 File Server, 24 MCP Gateway
ipAlamat IP lokal tujuan penerusan tunnel.Alamat IP yang valid, misalnya 127.0.0.1
portPort lokal.1 sampai 65534
pathFolder lokal yang akan dibagikan.Wajib hanya untuk File Server

Jawabannya 201 Created dengan tunnel baru. Catat id dan url-nya.

Mulai tunnel #

Bash
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 #

MetodePathTujuan
GET/tunnelsMencantumkan semua tunnel Anda.
GET/tunnels/{tunnelId}Mengambil satu tunnel.
POST/tunnels/http/random-subdomainMembuat tunnel HTTP, File Server, atau MCP Gateway dengan subdomain acak.
POST/tunnels/http/custom-subdomainMembuat satu dengan subdomain pilihan Anda.
POST/tunnels/http/custom-domainMembuat satu di domain Anda sendiri.
POST/tunnels/tcp-udpMembuat tunnel TCP, UDP, atau gabungan TCP dan UDP.
POST/tunnels/proxyMembuat tunnel proxy HTTP, SOCKS5, Shadowsocks, atau VLESS.
POST/tunnels/proxy/with-detailMembuat tunnel proxy dan mengembalikan detail koneksi lengkapnya.
POST/tunnels/shared-proxyMembuat tunnel proxy bersama (rotasi).
POST/tunnels/{tunnelId}/actions/startMemulai tunnel.
POST/tunnels/{tunnelId}/actions/stopMenghentikan tunnel.
DELETE/tunnels/{tunnelId}Menghapus tunnel secara permanen.
PATCH/tunnels/{tunnelId}/titleMengubah judul.
PATCH/tunnels/{tunnelId}/local-ipMengubah alamat IP lokal.
PATCH/tunnels/{tunnelId}/local-portMengubah port lokal.
PATCH/tunnels/{tunnelId}/port-reservedMengaktifkan atau menonaktifkan reservasi port tunnel TCP/UDP.
PATCH/tunnels/{tunnelId}/legacy-connectMengaktifkan atau menonaktifkan mode koneksi lama.
PATCH/tunnels/{tunnelId}/protocol-typeMengubah protokol proxy dari tunnel proxy.
GET/tunnels/{tunnelId}/request-logsLog permintaan HTTP terbaru dari tunnel HTTP atau File Server.

Operasi tunnel massal #

MetodePathTujuan
POST/tunnels/bulk/http/random-subdomainMembuat beberapa tunnel HTTP dengan subdomain acak.
POST/tunnels/bulk/http/custom-subdomainMembuat beberapa dengan subdomain kustom.
POST/tunnels/bulk/http/custom-domainMembuat beberapa di domain kustom.
POST/tunnels/bulk/tcp-udpMembuat beberapa tunnel TCP/UDP.
POST/tunnels/bulk/proxyMembuat beberapa tunnel proxy.
POST/tunnels/bulk/proxy/with-detailMembuat beberapa tunnel proxy dan mengembalikan detail koneksinya.
POST/tunnels/bulk/shared-proxyMembuat beberapa tunnel proxy bersama (rotasi).
POST/tunnels/bulk/actions/startMemulai beberapa tunnel. Body: array ID tunnel, misalnya [123, 456].
POST/tunnels/bulk/actions/stopMenghentikan beberapa tunnel. Body: array ID tunnel.
DELETE/tunnels/bulkMenghapus beberapa tunnel. Body: array ID tunnel.
PATCH/tunnels/bulk/protocol-typeMengubah 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.

MetodePath setelah /tunnels/{tunnelId}Tujuan
GET, POST, PATCH, DELETE/ip-restrictionsMencantumkan, menambah, mengatur mode izinkan atau tolak, atau menghapus semua pembatasan IP. Hapus satu dengan /ip-restrictions/{restrictionId}.
GET, POST, PATCH, DELETE/access-controlsHal yang sama untuk kontrol akses path URL. Hapus satu dengan /access-controls/{controlId}.
GET, PATCH/headersHeader HTTP kustom.
GET, PATCH/authenticationAutentikasi Dasar HTTP.
GET, PATCH/expirationTanggal kedaluwarsa tunnel.
GET, PATCH/server-portPort sisi server dari tunnel TCP/UDP.
GET, PATCH/http-timeoutBatas waktu permintaan HTTP.
GET, PATCH/rate-limitBatas kecepatan.
GET, PATCH/bandwidth-limitBatas total transfer data.
GET/bandwidth-usagePenggunaan bandwidth saat ini. Atur ulang penghitung dengan POST /bandwidth-usage/reset.
GET, PATCH/argumentsArgumen baris perintah kustom untuk tunnel.
GET, POST/shared-proxy-clientsMencantumkan atau menambah klien tunnel proxy bersama (rotasi). Perbarui atau hapus satu dengan PATCH atau DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsSemua pengaturan lanjutan tunnel dalam satu jawaban.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3Membaca atau mengganti satu pengaturan lanjutan.
PATCH/ssl-streamMengganti pengaturan SSL stream.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessMembaca atau mengubah satu nilai.
GET, PUT/token-groupsGrup token yang ditetapkan ke tunnel.
GET, PATCH/serverServer tunnel.

AuthToken #

MetodePathTujuan
GET/auth-tokensMencantumkan AuthToken Anda.
GET/auth-tokens/detailMencantumkan AuthToken Anda beserta detailnya.
GET/auth-tokens/{token}Detail satu AuthToken.
POST/auth-tokensMembuat AuthToken.
DELETE/auth-tokens/{token}Menghapus AuthToken.
GET/auth-tokens/{token}/tunnelsTunnel milik sebuah AuthToken.
GET/auth-tokens/{token}/ip-historyRiwayat perubahan alamat IP publik perangkat.
GET, PATCH/auth-tokens/{token}/airplane-mode-settingsPengaturan 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}/argumentsArgumen klien yang disimpan pada AuthToken.

Grup token #

MetodePathTujuan
GET/token-groupsMencantumkan grup token Anda.
GET/token-groups/{id}Mengambil satu grup token.
POST/token-groupsMembuat grup token.
DELETE/token-groups/{id}Menghapus grup token.
POST/token-groups/{id}/auth-tokensMenambahkan AuthToken ke grup.
DELETE/token-groups/{id}/auth-tokens/{tokenId}Menghapus AuthToken dari grup.

Server #

MetodePathTujuan
GET/serversMencantumkan server tempat Anda dapat membuat tunnel, beserta serverCode yang dipakai pada permintaan pembuatan.

Penyedia SSO #

MetodePathTujuan
GET/sso-providersMencantumkan penyedia SSO Anda.
GET/sso-providers/default-endpointsEndpoint default untuk satu jenis penyedia SSO.
POST/sso-providersMembuat 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.

MetodePath setelah /tunnels/{tunnelId}/vpn-accessTujuan
GET(tidak ada)Mencantumkan perangkat VPN tunnel.
POST(tidak ada)Membuat perangkat VPN.
DELETE/{peerId}Menghapus (mencabut) perangkat VPN.
POST/{peerId}/regenerateMembuat ulang kunci perangkat VPN.
GET/{peerId}/configMengunduh file konfigurasi perangkat VPN.
GET/{peerId}/qrKode QR konfigurasi perangkat WireGuard.
GET/{peerId}/credentialsNama 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.

Dukungan