Localtonet REST API
Bu sayfada 8 bölüm
- Etkileşimli başvuru
- Başlamadan önce
- Temel URL ve kimlik doğrulama
- Kurallar
- Hatalar
- Hız sınırları
- Örnekler
- Tünellerinizi listeleme
- Rastgele alt alan adıyla HTTP tüneli oluşturma
- Tüneli başlatın
- Uç nokta grupları
- Tüneller
- Toplu tünel işlemleri
- Tünel yapılandırması
- AuthToken'lar
- Token grupları
- Sunucular
- SSO sağlayıcıları
- VPN erişimi
- Sorun giderme
- İlgili sayfalar
REST API v2, tüneller için panelin yaptığı işleri yapar: tünel oluşturma, başlatma, durdurma, silme ve yapılandırma; ayrıca AuthToken'ları, token gruplarını ve SSO sağlayıcılarını yönetme. Her isteği API anahtarınızla doğrularsınız.
Etkileşimli başvuru #
Tüm uç noktalar, istek ve yanıt modelleriyle ve denemek için bir formla birlikte etkileşimli başvuruda yer alır:
- localtonet.com/api: API v2, güncel sürüm. Ona panelde API Arayüzü düğmesiyle de ulaşırsınız.
- localtonet.com/api/v1: API v1, mevcut entegrasyonlar için korunur. Yeni işlerde v2'yi kullanın.
Bu sayfa size kuralları ve uç nokta gruplarına genel bir bakış sunar. Bir isteğin tam alanları için uç noktayı başvuruda açın.
Başlamadan önce #
- API anahtarınız. Panel'i açın ve API Anahtarı kartındaki Kopyala düğmesini kullanın. Hesap ve güvenlik sayfasına bakın.
- Tünel oluşturmak için: tüneli çalıştıracak cihazın bir AuthToken'ı ve o token ile bağlı bir Localtonet istemcisi. AuthToken'lar sayfasına bakın.
API anahtarınızı gizli tutun. Ona sahip olan herkes tünellerinizi ve token'larınızı oluşturabilir, değiştirebilir ve silebilir. API Anahtarı kartındaki Değiştir düğmesi yeni bir anahtar oluşturur ve eskisini geçersiz kılar.
Temel URL ve kimlik doğrulama #
Tüm v2 uç noktaları şununla başlar:
https://localtonet.com/api/v2API anahtarını her isteğin Authorization başlığında Bearer token olarak gönderin:
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>Bir ekip panelinde kopyalanan API anahtarı, o ekipteki AuthToken'larınızı ve tünellerinizi listeler; kendi hesabınızın anahtarı ise hiçbir ekibe ait olmayan AuthToken'ları listeler.
Kurallar #
| Konu | API nasıl davranır |
|---|---|
| Biçim | İstek ve yanıt gövdeleri JSON'dır. Gövde gönderirken Content-Type: application/json gönderin. |
| Tünel kimliği | Yoldaki tunnelId, liste ve oluşturma uç noktalarının döndürdüğü tünelin sayısal id değeridir. |
| Yoldaki AuthToken | {token}, AuthToken dizesinin kendisidir. |
| Başarı kodları | Okumalar için gövdeli 200, çoğu oluşturma için 201 (tünel oluşturma uç noktaları yeni tüneli döndürür), çoğu eylem ve güncelleme için gövdesiz 204. Başvuru her uç noktanın yanıtını gösterir. |
| Toplu uç noktalar | /bulk/ içeren yollar bir JSON dizisi alır ve istek başına en fazla 100 öğe kabul eder (/tunnels/bulk/protocol-type: en fazla 500). |
| Yeni tüneller | Oluşturduğunuz tünel henüz çalışmaz. Onu başlatma eylemiyle başlatın. Yalnızca proxy/with-detail uç noktaları tüneli aynı çağrıda isStartAfterCreate ile başlatabilir. |
Hatalar #
| Durum | Anlamı | Gövde |
|---|---|---|
400 | İstek gövdesi geçerli değil veya işlem reddedildi; örneğin planınızın bir limiti nedeniyle. | Çoğu uç noktada JSON biçiminde bir sorun nesnesi; title iletiyi içerir. Doğrulama hataları ve toplu uç noktaların hataları errors altında listelenir. |
401 | API anahtarı eksik veya geçersiz. | Belirli bir ileti yok |
403, 409 | Değişikliğe izin verilmediğinde veya mevcut yapılandırmayla çakıştığında bazı tünel yapılandırma ve VPN erişimi uç noktaları tarafından döndürülür. | İletinin title içinde olduğu bir sorun nesnesi. |
404 | Tünel veya nesne bulunamadı ya da size ait değil. | Boş veya bir sorun nesnesi |
429 | Çok fazla istek. | Aşağıdaki hız sınırlarına bakın. |
Hız sınırları #
İstekler hız sınırına tabidir. Sınırı aşan bir isteğe 429 Too Many Requests ile yanıt verilir. Bekleyin ve yeniden gönderin; çok sayıda tekli çağrı yerine toplu uç noktaları kullanın.
Örnekler #
<YOUR_API_KEY> yerine API anahtarınızı, <YOUR_TOKEN> yerine cihazın AuthToken'ını yazın.
Tünellerinizi listeleme #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"Yanıt, her tünel için bir nesne içeren bir JSON dizisidir. Alanları arasında id, title, url (herkese açık adres), protocolType, authToken, serverId, clientIp ve clientPort (yerel hedef), status ve connectionStatus bulunur. Henüz hiç tünel oluşturmadıysanız yanıt boş bir dizi yerine 404 olur.
Rastgele alt alan adıyla HTTP tüneli oluşturma #
Önce kullanmak istediğiniz sunucunun kodunu alın:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"Her girişte bir serverCode, bir serverName ve bir serverDomain vardır. Ardından tüneli oluşturun. Bu örnek, cihazın 3000 portundaki bir web uygulamasına yönlendirir:
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
}'| Alan | Anlamı | Değerler |
|---|---|---|
authToken | Tüneli çalıştıran cihazın AuthToken'ı. | Zorunlu |
serverCode | Sunucu, GET /servers çıktısından. | Zorunlu |
protocolType | Tünel türü. | 1 HTTP, 5 File Server, 24 MCP Gateway |
ip | Tünelin yönlendirdiği yerel IP adresi. | Geçerli bir IP adresi, örneğin 127.0.0.1 |
port | Yerel port. | 1 ile 65534 arası |
path | Paylaşılacak yerel klasör. | Yalnızca File Server için zorunlu |
Yanıt, yeni tünelle birlikte 201 Created olur. id ve url değerlerini not alın.
Tüneli başlatın #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"Yanıt 204 No Content olur. Cihazın istemcisi bağlı olduğunda tünele url adresinden ulaşılabilir. Tekrar durdurmak için /actions/stop kullanın.
Uç nokta grupları #
Aşağıdaki tüm yollar https://localtonet.com/api/v2 adresine görecelidir.
Tüneller #
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /tunnels | Tüm tünellerinizi listeler. |
| GET | /tunnels/{tunnelId} | Tek bir tüneli getirir. |
| POST | /tunnels/http/random-subdomain | Rastgele alt alan adıyla bir HTTP, File Server veya MCP Gateway tüneli oluşturur. |
| POST | /tunnels/http/custom-subdomain | Seçtiğiniz bir alt alan adıyla tünel oluşturur. |
| POST | /tunnels/http/custom-domain | Kendi alan adınızda tünel oluşturur. |
| POST | /tunnels/tcp-udp | Bir TCP, UDP veya birleşik TCP ve UDP tüneli oluşturur. |
| POST | /tunnels/proxy | Bir HTTP, SOCKS5, Shadowsocks veya VLESS proxy tüneli oluşturur. |
| POST | /tunnels/proxy/with-detail | Bir proxy tüneli oluşturur ve tüm bağlantı ayrıntılarını döndürür. |
| POST | /tunnels/shared-proxy | Paylaşılan (rotasyonlu) bir proxy tüneli oluşturur. |
| POST | /tunnels/{tunnelId}/actions/start | Bir tüneli başlatır. |
| POST | /tunnels/{tunnelId}/actions/stop | Bir tüneli durdurur. |
| DELETE | /tunnels/{tunnelId} | Bir tüneli kalıcı olarak siler. |
| PATCH | /tunnels/{tunnelId}/title | Başlığı değiştirir. |
| PATCH | /tunnels/{tunnelId}/local-ip | Yerel IP adresini değiştirir. |
| PATCH | /tunnels/{tunnelId}/local-port | Yerel portu değiştirir. |
| PATCH | /tunnels/{tunnelId}/port-reserved | Bir TCP/UDP tünelinin port rezervasyonunu açar veya kapatır. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | Eski bağlantı modunu açar veya kapatır. |
| PATCH | /tunnels/{tunnelId}/protocol-type | Bir proxy tünelinin proxy protokolünü değiştirir. |
| GET | /tunnels/{tunnelId}/request-logs | Bir HTTP veya File Server tünelinin son HTTP istek günlükleri. |
Toplu tünel işlemleri #
| Yöntem | Yol | Amaç |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | Rastgele alt alan adlarıyla birden fazla HTTP tüneli oluşturur. |
| POST | /tunnels/bulk/http/custom-subdomain | Özel alt alan adlarıyla birden fazla tünel oluşturur. |
| POST | /tunnels/bulk/http/custom-domain | Özel alan adlarında birden fazla tünel oluşturur. |
| POST | /tunnels/bulk/tcp-udp | Birden fazla TCP/UDP tüneli oluşturur. |
| POST | /tunnels/bulk/proxy | Birden fazla proxy tüneli oluşturur. |
| POST | /tunnels/bulk/proxy/with-detail | Birden fazla proxy tüneli oluşturur ve bağlantı ayrıntılarını döndürür. |
| POST | /tunnels/bulk/shared-proxy | Birden fazla paylaşılan (rotasyonlu) proxy tüneli oluşturur. |
| POST | /tunnels/bulk/actions/start | Birden fazla tüneli başlatır. Gövde: tünel kimliklerinden oluşan bir dizi, örneğin [123, 456]. |
| POST | /tunnels/bulk/actions/stop | Birden fazla tüneli durdurur. Gövde: tünel kimliklerinden oluşan bir dizi. |
| DELETE | /tunnels/bulk | Birden fazla tüneli siler. Gövde: tünel kimliklerinden oluşan bir dizi. |
| PATCH | /tunnels/bulk/protocol-type | Birden fazla proxy tünelinin proxy protokolünü değiştirir. |
Tünel yapılandırması #
Bu uç noktalar tek bir tünelin ayarlarını değiştirir. Hepsi /tunnels/{tunnelId} ile başlar. Her ayarın ne yaptığı Ayarlar başvurusunda anlatılır.
| Yöntemler | /tunnels/{tunnelId} sonrasındaki yol | Amaç |
|---|---|---|
| GET, POST, PATCH, DELETE | /ip-restrictions | Tüm IP kısıtlamalarını listeler, ekler, izin ver veya reddet modunu ayarlar ya da siler. Birini /ip-restrictions/{restrictionId} ile silin. |
| GET, POST, PATCH, DELETE | /access-controls | URL yolu erişim denetimleri için aynısı. Birini /access-controls/{controlId} ile silin. |
| GET, PATCH | /headers | Özel HTTP başlıkları. |
| GET, PATCH | /authentication | HTTP Temel Kimlik Doğrulaması. |
| GET, PATCH | /expiration | Tünelin son kullanma tarihi. |
| GET, PATCH | /server-port | Bir TCP/UDP tünelinin sunucu tarafı portu. |
| GET, PATCH | /http-timeout | HTTP istek zaman aşımı. |
| GET, PATCH | /rate-limit | Hız sınırı. |
| GET, PATCH | /bandwidth-limit | Toplam veri aktarımı sınırı. |
| GET | /bandwidth-usage | Güncel bant genişliği kullanımı. Sayacı POST /bandwidth-usage/reset ile sıfırlayın. |
| GET, PATCH | /arguments | Tünel için özel komut satırı bağımsız değişkenleri. |
| GET, POST | /shared-proxy-clients | Paylaşılan (rotasyonlu) bir proxy tünelinin istemcilerini listeler veya ekler. Birini PATCH veya DELETE /shared-proxy-clients/{clientId} ile güncelleyin ya da silin. |
| GET | /advanced-settings | Tünelin tüm gelişmiş ayarları tek bir yanıtta. |
| GET, PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | Bir gelişmiş ayarı okur veya değiştirir. |
| PATCH | /ssl-stream | SSL akışı ayarını değiştirir. |
| GET, PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | Bir değeri okur veya değiştirir. |
| GET, PUT | /token-groups | Tünele atanmış token grupları. |
| GET, PATCH | /server | Tünelin sunucusu. |
AuthToken'lar #
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /auth-tokens | AuthToken'larınızı listeler. |
| GET | /auth-tokens/detail | AuthToken'larınızı ayrıntılarıyla listeler. |
| GET | /auth-tokens/{token} | Bir AuthToken'ın ayrıntıları. |
| POST | /auth-tokens | Bir AuthToken oluşturur. |
| DELETE | /auth-tokens/{token} | Bir AuthToken'ı siler. |
| GET | /auth-tokens/{token}/tunnels | Bir AuthToken'ın tünelleri. |
| GET | /auth-tokens/{token}/ip-history | Cihazın herkese açık IP adresi değişiklik geçmişi. |
| GET, PATCH | /auth-tokens/{token}/airplane-mode-settings | Uçak modu otomasyon ayarları. |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | Bir IP değiştirme bağlantısı ekler. |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | Bir IP değiştirme bağlantısını siler. |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | Bir cihaz yeniden başlatma bağlantısı ekler. |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | Bir cihaz yeniden başlatma bağlantısını siler. |
| GET, PATCH | /auth-tokens/{token}/arguments | AuthToken üzerinde kayıtlı istemci bağımsız değişkenleri. |
Token grupları #
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /token-groups | Token gruplarınızı listeler. |
| GET | /token-groups/{id} | Tek bir token grubunu getirir. |
| POST | /token-groups | Bir token grubu oluşturur. |
| DELETE | /token-groups/{id} | Bir token grubunu siler. |
| POST | /token-groups/{id}/auth-tokens | Gruba bir AuthToken ekler. |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | Bir AuthToken'ı gruptan çıkarır. |
Sunucular #
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /servers | Tünel oluşturabileceğiniz sunucuları, oluşturma isteklerinde kullanılacak serverCode ile birlikte listeler. |
SSO sağlayıcıları #
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /sso-providers | SSO sağlayıcılarınızı listeler. |
| GET | /sso-providers/default-endpoints | Bir SSO sağlayıcı türünün varsayılan uç noktaları. |
| POST | /sso-providers | Bir SSO sağlayıcısı oluşturur veya günceller. |
| DELETE | /sso-providers/{id} | Bir SSO sağlayıcısını siler. |
| GET | /sso-providers/tunnel/{tunnelId} | Bir tünel için yapılandırılmış SSO sağlayıcıları. Burada tunnelId, tünelin GUID değeridir (guidId). |
| PUT | /sso-providers/tunnel/{tunnelId} | Bir tünelin SSO sağlayıcılarını kaydeder. |
Sağlayıcıların ne yaptığını öğrenmek için Tek Oturum Açma sayfasına bakın.
VPN erişimi #
VPN erişimi, bir proxy tüneli üzerinde WireGuard veya OpenVPN cihaz profili verir; o cihazın tüm trafiği proxy üzerinden çıkar. Bu uç noktalar /tunnels/{tunnelId}/vpn-access ile başlar.
| Yöntem | /tunnels/{tunnelId}/vpn-access sonrasındaki yol | Amaç |
|---|---|---|
| GET | (yok) | Tünelin VPN cihazlarını listeler. |
| POST | (yok) | Bir VPN cihazı oluşturur. |
| DELETE | /{peerId} | Bir VPN cihazını siler (iptal eder). |
| POST | /{peerId}/regenerate | Bir VPN cihazının anahtarlarını yeniden oluşturur. |
| GET | /{peerId}/config | Bir VPN cihazının yapılandırma dosyasını indirir. |
| GET | /{peerId}/qr | Bir WireGuard cihaz yapılandırmasının QR kodu. |
| GET | /{peerId}/credentials | Bir OpenVPN cihazının kullanıcı adı ve parolası. |
Sorun giderme #
Her istek 401 döndürüyor
Başlığı kontrol edin: Authorization: Bearer ve ardından bir boşluk ve anahtar olmalı, anahtarın etrafında tırnak bulunmamalıdır. API Anahtarı kartında Değiştir düğmesini seçtiyseniz eski anahtar artık çalışmaz; yenisini kopyalayın.
Ekibimin AuthToken'larını görmüyorum
Kendi hesabınızın API anahtarını kullanıyorsunuz. Ekip paneline geçin ve API anahtarını orada kopyalayın.
Tünel oluşturuldu ama adresi yanıt vermiyor
Yeni bir tünel durdurulmuş olarak gelir. POST /tunnels/{tunnelId}/actions/start çağrısını yapın ve cihazın Localtonet istemcisinin kullandığınız AuthToken ile çalıştığını kontrol edin.
429 Too Many Requests alıyorum
İstekler hız sınırına tabidir. Bekleyin, ardından isteği yeniden gönderin ve tekli çağrı döngülerini tek bir toplu istekle değiştirin.