본문으로 건너뛰기
Localtonet Localtonet 대시보드

Localtonet REST API

이 페이지 도움받기
이 페이지의 내용 섹션 8개
  1. 대화형 레퍼런스
  2. 시작하기 전에
  3. 기본 URL과 인증
  4. 규칙
  5. 오류
  6. 요청 제한
  7. 예시
  8. 터널 나열하기
  9. 임의의 서브도메인으로 HTTP 터널 만들기
  10. 터널 시작하기
  11. 엔드포인트 그룹
  12. 터널
  13. 대량 터널 작업
  14. 터널 구성
  15. AuthToken
  16. 토큰 그룹
  17. 서버
  18. SSO 공급자
  19. VPN 접근
  20. 문제 해결
  21. 관련 페이지

REST API v2는 대시보드에서 하는 터널 작업을 그대로 수행합니다. 터널을 만들고, 시작하고, 중지하고, 삭제하고, 설정할 수 있으며 AuthToken, 토큰 그룹, SSO 공급자도 관리할 수 있습니다. 모든 요청은 API 키로 인증합니다.

대화형 레퍼런스 #

모든 엔드포인트의 요청 및 응답 모델과 직접 시험해 볼 수 있는 폼은 대화형 레퍼런스에 있습니다.

  • localtonet.com/api: 현재 버전인 API v2입니다. 대시보드의 API UI 버튼으로도 열 수 있습니다.
  • localtonet.com/api/v1: 기존 연동을 위해 유지되는 API v1입니다. 새로 개발할 때는 v2를 사용하세요.

이 페이지에서는 규칙과 엔드포인트 그룹의 개요를 설명합니다. 요청의 정확한 필드는 레퍼런스에서 해당 엔드포인트를 열어 확인하세요.

시작하기 전에 #

  • 내 API 키. 대시보드를 열고 API 키 카드에서 복사를 사용하세요. 계정 및 보안을 참고하세요.
  • 터널을 만들려면 터널을 실행할 기기의 AuthToken과 그 토큰으로 연결된 Localtonet 클라이언트가 필요합니다. AuthToken을 참고하세요.

API 키를 비공개로 유지하세요. 키를 가진 사람은 누구나 내 터널과 토큰을 만들고, 변경하고, 삭제할 수 있습니다. API 키 카드의 변경은 새 키를 만들고 이전 키를 무효화합니다.

기본 URL과 인증 #

모든 v2 엔드포인트는 다음으로 시작합니다.

기본 URL
https://localtonet.com/api/v2

모든 요청의 Authorization 헤더에 API 키를 Bearer 토큰으로 보내세요.

HTTP
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>

팀 대시보드에서 복사한 API 키는 해당 팀의 AuthToken과 터널을 나열하고, 내 계정의 키는 어떤 팀에도 속하지 않은 AuthToken을 나열합니다.

규칙 #

주제API의 동작 방식
형식요청 및 응답 본문은 JSON입니다. 본문을 보낼 때는 Content-Type: application/json을 함께 보내세요.
터널 ID경로의 tunnelId는 목록 및 생성 엔드포인트가 반환하는 터널의 숫자형 id입니다.
경로의 AuthToken{token}은 AuthToken 문자열 자체입니다.
성공 코드조회는 본문이 있는 200, 대부분의 생성은 201(터널 생성 엔드포인트는 새 터널을 반환합니다), 대부분의 동작과 업데이트는 본문이 없는 204입니다. 각 엔드포인트의 응답은 레퍼런스에 나와 있습니다.
대량 엔드포인트경로에 /bulk/가 포함된 엔드포인트는 JSON 배열을 받으며 요청당 최대 100개 항목을 처리합니다(/tunnels/bulk/protocol-type은 최대 500개).
새 터널새로 만든 터널은 아직 실행 중이 아닙니다. start 동작으로 시작하세요. proxy/with-detail 엔드포인트만 isStartAfterCreate로 같은 호출에서 터널을 시작할 수 있습니다.

오류 #

상태의미본문
400요청 본문이 올바르지 않거나 요금제 한도 등의 이유로 작업이 거부되었습니다.대부분의 엔드포인트는 JSON 문제 객체를 반환하며 title에 메시지가 들어 있습니다. 유효성 검사 오류와 대량 엔드포인트의 오류는 errors 아래에 나열됩니다.
401API 키가 없거나 올바르지 않습니다.특정 메시지 없음
403, 409일부 터널 구성 및 VPN 접근 엔드포인트에서 변경이 허용되지 않거나 현재 구성과 충돌할 때 반환됩니다.title에 메시지가 담긴 문제 객체.
404터널 또는 객체를 찾을 수 없거나 내 소유가 아닙니다.비어 있거나 문제 객체
429요청이 너무 많습니다.아래의 요청 제한을 참고하세요.

요청 제한 #

요청에는 속도 제한이 있습니다. 제한을 초과한 요청에는 429 Too Many Requests로 응답합니다. 잠시 기다린 후 다시 보내고, 개별 호출을 여러 번 보내는 대신 대량 엔드포인트를 사용하세요.

예시 #

<YOUR_API_KEY>를 내 API 키로, <YOUR_TOKEN>을 기기의 AuthToken으로 바꾸세요.

터널 나열하기 #

Bash
curl https://localtonet.com/api/v2/tunnels \
  -H "Authorization: Bearer <YOUR_API_KEY>"

응답은 터널당 객체 하나로 이루어진 JSON 배열입니다. 필드에는 id, title, url(공개 주소), protocolType, authToken, serverId, clientIp와 clientPort(로컬 대상), status, connectionStatus 등이 있습니다. 아직 터널이 없으면 빈 배열 대신 404가 반환됩니다.

임의의 서브도메인으로 HTTP 터널 만들기 #

먼저 사용할 서버의 코드를 가져옵니다.

Bash
curl https://localtonet.com/api/v2/servers \
  -H "Authorization: Bearer <YOUR_API_KEY>"

각 항목에는 serverCode, serverName, serverDomain이 있습니다. 그런 다음 터널을 만드세요. 이 예시는 기기의 3000번 포트에서 실행 중인 웹 앱으로 전달합니다.

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
  }'
필드의미값
authToken터널을 실행하는 기기의 AuthToken.필수
serverCodeGET /servers에서 가져온 서버.필수
protocolType터널 유형.1 HTTP, 5 File Server, 24 MCP Gateway
ip터널이 전달할 로컬 IP 주소.127.0.0.1 같은 올바른 IP 주소
port로컬 포트.1~65534
path공유할 로컬 폴더.File Server에서만 필수

응답은 새 터널과 함께 201 Created입니다. id와 url을 기록해 두세요.

터널 시작하기 #

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
  -H "Authorization: Bearer <YOUR_API_KEY>"

응답은 204 No Content입니다. 기기의 클라이언트가 연결되어 있으면 터널이 url로 접속 가능해집니다. 다시 중지하려면 /actions/stop을 사용하세요.

엔드포인트 그룹 #

아래의 모든 경로는 https://localtonet.com/api/v2를 기준으로 한 상대 경로입니다.

터널 #

메서드경로용도
GET/tunnels내 모든 터널을 나열합니다.
GET/tunnels/{tunnelId}터널 하나를 가져옵니다.
POST/tunnels/http/random-subdomain임의의 서브도메인으로 HTTP, File Server 또는 MCP Gateway 터널을 만듭니다.
POST/tunnels/http/custom-subdomain내가 정한 서브도메인으로 터널을 만듭니다.
POST/tunnels/http/custom-domain내 도메인으로 터널을 만듭니다.
POST/tunnels/tcp-udpTCP, UDP 또는 TCP와 UDP 결합 터널을 만듭니다.
POST/tunnels/proxyHTTP, SOCKS5, Shadowsocks 또는 VLESS 프록시 터널을 만듭니다.
POST/tunnels/proxy/with-detail프록시 터널을 만들고 전체 연결 세부 정보를 반환합니다.
POST/tunnels/shared-proxy공유(로테이팅) 프록시 터널을 만듭니다.
POST/tunnels/{tunnelId}/actions/start터널을 시작합니다.
POST/tunnels/{tunnelId}/actions/stop터널을 중지합니다.
DELETE/tunnels/{tunnelId}터널을 영구적으로 삭제합니다.
PATCH/tunnels/{tunnelId}/title제목을 변경합니다.
PATCH/tunnels/{tunnelId}/local-ip로컬 IP 주소를 변경합니다.
PATCH/tunnels/{tunnelId}/local-port로컬 포트를 변경합니다.
PATCH/tunnels/{tunnelId}/port-reservedTCP/UDP 터널의 포트 예약을 켜거나 끕니다.
PATCH/tunnels/{tunnelId}/legacy-connect레거시 연결 모드를 켜거나 끕니다.
PATCH/tunnels/{tunnelId}/protocol-type프록시 터널의 프록시 프로토콜을 변경합니다.
GET/tunnels/{tunnelId}/request-logsHTTP 또는 File Server 터널의 최근 HTTP 요청 로그.

대량 터널 작업 #

메서드경로용도
POST/tunnels/bulk/http/random-subdomain임의의 서브도메인으로 HTTP 터널을 여러 개 만듭니다.
POST/tunnels/bulk/http/custom-subdomain커스텀 서브도메인으로 여러 개를 만듭니다.
POST/tunnels/bulk/http/custom-domain커스텀 도메인으로 여러 개를 만듭니다.
POST/tunnels/bulk/tcp-udpTCP/UDP 터널을 여러 개 만듭니다.
POST/tunnels/bulk/proxy프록시 터널을 여러 개 만듭니다.
POST/tunnels/bulk/proxy/with-detail프록시 터널을 여러 개 만들고 연결 세부 정보를 반환합니다.
POST/tunnels/bulk/shared-proxy공유(로테이팅) 프록시 터널을 여러 개 만듭니다.
POST/tunnels/bulk/actions/start터널 여러 개를 시작합니다. 본문: [123, 456] 같은 터널 ID 배열.
POST/tunnels/bulk/actions/stop터널 여러 개를 중지합니다. 본문: 터널 ID 배열.
DELETE/tunnels/bulk터널 여러 개를 삭제합니다. 본문: 터널 ID 배열.
PATCH/tunnels/bulk/protocol-type프록시 터널 여러 개의 프록시 프로토콜을 변경합니다.

터널 구성 #

이 엔드포인트는 터널 하나의 설정을 변경합니다. 모두 /tunnels/{tunnelId}로 시작합니다. 각 설정의 기능은 설정 참조에서 설명합니다.

메서드/tunnels/{tunnelId} 뒤의 경로용도
GET, POST, PATCH, DELETE/ip-restrictionsIP 제한을 나열하거나 추가하고, 허용 또는 거부 모드를 설정하거나, 전체를 삭제합니다. 하나만 삭제하려면 /ip-restrictions/{restrictionId}를 사용하세요.
GET, POST, PATCH, DELETE/access-controlsURL 경로 접근 제어도 같은 방식으로 사용합니다. 하나만 삭제하려면 /access-controls/{controlId}를 사용하세요.
GET, PATCH/headers커스텀 HTTP 헤더.
GET, PATCH/authenticationHTTP 기본 인증.
GET, PATCH/expiration터널의 만료일.
GET, PATCH/server-portTCP/UDP 터널의 서버 측 포트.
GET, PATCH/http-timeoutHTTP 요청 타임아웃.
GET, PATCH/rate-limit속도 제한.
GET, PATCH/bandwidth-limit총 데이터 전송 제한.
GET/bandwidth-usage현재 대역폭 사용량. 카운터는 POST /bandwidth-usage/reset으로 초기화합니다.
GET, PATCH/arguments터널의 커스텀 명령줄 인수.
GET, POST/shared-proxy-clients공유(로테이팅) 프록시 터널의 클라이언트를 나열하거나 추가합니다. 하나를 업데이트하거나 삭제하려면 PATCH 또는 DELETE /shared-proxy-clients/{clientId}를 사용하세요.
GET/advanced-settings터널의 모든 고급 설정을 한 번의 응답으로 가져옵니다.
GET, PATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3고급 설정 하나를 읽거나 전환합니다.
PATCH/ssl-streamSSL 스트림 설정을 전환합니다.
GET, PATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless값 하나를 읽거나 변경합니다.
GET, PUT/token-groups터널에 할당된 토큰 그룹.
GET, PATCH/server터널의 서버.

AuthToken #

메서드경로용도
GET/auth-tokens내 AuthToken을 나열합니다.
GET/auth-tokens/detail내 AuthToken을 세부 정보와 함께 나열합니다.
GET/auth-tokens/{token}AuthToken 하나의 세부 정보.
POST/auth-tokensAuthToken을 만듭니다.
DELETE/auth-tokens/{token}AuthToken을 삭제합니다.
GET/auth-tokens/{token}/tunnelsAuthToken의 터널.
GET/auth-tokens/{token}/ip-history기기의 공인 IP 주소 변경 기록.
GET, PATCH/auth-tokens/{token}/airplane-mode-settings비행기 모드 자동화 설정.
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}IP 변경 링크를 추가합니다.
DELETE/auth-tokens/{token}/change-ip-links/{id}IP 변경 링크를 삭제합니다.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}기기 재시작 링크를 추가합니다.
DELETE/auth-tokens/{token}/restart-device-links/{id}기기 재시작 링크를 삭제합니다.
GET, PATCH/auth-tokens/{token}/argumentsAuthToken에 저장된 클라이언트 인수.

토큰 그룹 #

메서드경로용도
GET/token-groups내 토큰 그룹을 나열합니다.
GET/token-groups/{id}토큰 그룹 하나를 가져옵니다.
POST/token-groups토큰 그룹을 만듭니다.
DELETE/token-groups/{id}토큰 그룹을 삭제합니다.
POST/token-groups/{id}/auth-tokens그룹에 AuthToken을 추가합니다.
DELETE/token-groups/{id}/auth-tokens/{tokenId}그룹에서 AuthToken을 제거합니다.

서버 #

메서드경로용도
GET/servers터널을 만들 수 있는 서버를 나열하며, 생성 요청에 사용할 serverCode를 함께 제공합니다.

SSO 공급자 #

메서드경로용도
GET/sso-providers내 SSO 공급자를 나열합니다.
GET/sso-providers/default-endpointsSSO 공급자 유형의 기본 엔드포인트.
POST/sso-providersSSO 공급자를 만들거나 업데이트합니다.
DELETE/sso-providers/{id}SSO 공급자를 삭제합니다.
GET/sso-providers/tunnel/{tunnelId}터널에 구성된 SSO 공급자. 여기서 tunnelId는 터널의 GUID(guidId)입니다.
PUT/sso-providers/tunnel/{tunnelId}터널의 SSO 공급자를 저장합니다.

공급자가 하는 일은 통합 인증(SSO)을 참고하세요.

VPN 접근 #

VPN 접근은 프록시 터널에 WireGuard 또는 OpenVPN 기기 프로필을 제공하며, 그 기기의 전체 트래픽이 프록시를 통해 나갑니다. 이 엔드포인트는 /tunnels/{tunnelId}/vpn-access로 시작합니다.

메서드/tunnels/{tunnelId}/vpn-access 뒤의 경로용도
GET(없음)터널의 VPN 기기를 나열합니다.
POST(없음)VPN 기기를 만듭니다.
DELETE/{peerId}VPN 기기를 삭제(폐기)합니다.
POST/{peerId}/regenerateVPN 기기의 키를 다시 생성합니다.
GET/{peerId}/configVPN 기기의 구성 파일을 다운로드합니다.
GET/{peerId}/qrWireGuard 기기 구성의 QR 코드.
GET/{peerId}/credentialsOpenVPN 기기의 사용자 이름과 비밀번호.

문제 해결 #

모든 요청이 401을 반환합니다

헤더를 확인하세요. Authorization: Bearer 뒤에 공백 하나와 키가 오고, 키에는 따옴표가 없어야 합니다. API 키 카드에서 변경을 선택했다면 이전 키는 더 이상 동작하지 않으므로 새 키를 복사하세요.

팀의 AuthToken이 보이지 않습니다

내 계정의 API 키를 사용하고 있습니다. 팀 대시보드로 전환하여 그곳에서 API 키를 복사하세요.

터널은 만들어졌는데 주소가 응답하지 않습니다

새 터널은 중지된 상태입니다. POST /tunnels/{tunnelId}/actions/start를 호출하고, 기기의 Localtonet 클라이언트가 사용한 AuthToken으로 실행 중인지 확인하세요.

429 Too Many Requests가 반환됩니다

요청에는 속도 제한이 있습니다. 잠시 기다린 후 요청을 다시 보내고, 개별 호출을 반복하는 대신 대량 요청 하나를 사용하세요.

이 페이지에 도움이 필요하신가요? 커뮤니티에 질문하거나 지원 티켓을 만들어 주세요.

지원