Localtonet REST API
이 페이지의 내용 섹션 8개
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 엔드포인트는 다음으로 시작합니다.
https://localtonet.com/api/v2모든 요청의 Authorization 헤더에 API 키를 Bearer 토큰으로 보내세요.
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 아래에 나열됩니다. |
401 | API 키가 없거나 올바르지 않습니다. | 특정 메시지 없음 |
403, 409 | 일부 터널 구성 및 VPN 접근 엔드포인트에서 변경이 허용되지 않거나 현재 구성과 충돌할 때 반환됩니다. | title에 메시지가 담긴 문제 객체. |
404 | 터널 또는 객체를 찾을 수 없거나 내 소유가 아닙니다. | 비어 있거나 문제 객체 |
429 | 요청이 너무 많습니다. | 아래의 요청 제한을 참고하세요. |
요청 제한 #
요청에는 속도 제한이 있습니다. 제한을 초과한 요청에는 429 Too Many Requests로 응답합니다. 잠시 기다린 후 다시 보내고, 개별 호출을 여러 번 보내는 대신 대량 엔드포인트를 사용하세요.
예시 #
<YOUR_API_KEY>를 내 API 키로, <YOUR_TOKEN>을 기기의 AuthToken으로 바꾸세요.
터널 나열하기 #
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 터널 만들기 #
먼저 사용할 서버의 코드를 가져옵니다.
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"각 항목에는 serverCode, serverName, serverDomain이 있습니다. 그런 다음 터널을 만드세요. 이 예시는 기기의 3000번 포트에서 실행 중인 웹 앱으로 전달합니다.
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. | 필수 |
serverCode | GET /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을 기록해 두세요.
터널 시작하기 #
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-udp | TCP, UDP 또는 TCP와 UDP 결합 터널을 만듭니다. |
| POST | /tunnels/proxy | HTTP, 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-reserved | TCP/UDP 터널의 포트 예약을 켜거나 끕니다. |
| PATCH | /tunnels/{tunnelId}/legacy-connect | 레거시 연결 모드를 켜거나 끕니다. |
| PATCH | /tunnels/{tunnelId}/protocol-type | 프록시 터널의 프록시 프로토콜을 변경합니다. |
| GET | /tunnels/{tunnelId}/request-logs | HTTP 또는 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-udp | TCP/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-restrictions | IP 제한을 나열하거나 추가하고, 허용 또는 거부 모드를 설정하거나, 전체를 삭제합니다. 하나만 삭제하려면 /ip-restrictions/{restrictionId}를 사용하세요. |
| GET, POST, PATCH, DELETE | /access-controls | URL 경로 접근 제어도 같은 방식으로 사용합니다. 하나만 삭제하려면 /access-controls/{controlId}를 사용하세요. |
| GET, PATCH | /headers | 커스텀 HTTP 헤더. |
| GET, PATCH | /authentication | HTTP 기본 인증. |
| GET, PATCH | /expiration | 터널의 만료일. |
| GET, PATCH | /server-port | TCP/UDP 터널의 서버 측 포트. |
| GET, PATCH | /http-timeout | HTTP 요청 타임아웃. |
| 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-stream | SSL 스트림 설정을 전환합니다. |
| 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-tokens | AuthToken을 만듭니다. |
| DELETE | /auth-tokens/{token} | AuthToken을 삭제합니다. |
| GET | /auth-tokens/{token}/tunnels | AuthToken의 터널. |
| 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}/arguments | AuthToken에 저장된 클라이언트 인수. |
토큰 그룹 #
| 메서드 | 경로 | 용도 |
|---|---|---|
| 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-endpoints | SSO 공급자 유형의 기본 엔드포인트. |
| POST | /sso-providers | SSO 공급자를 만들거나 업데이트합니다. |
| 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}/regenerate | VPN 기기의 키를 다시 생성합니다. |
| GET | /{peerId}/config | VPN 기기의 구성 파일을 다운로드합니다. |
| GET | /{peerId}/qr | WireGuard 기기 구성의 QR 코드. |
| GET | /{peerId}/credentials | OpenVPN 기기의 사용자 이름과 비밀번호. |
문제 해결 #
모든 요청이 401을 반환합니다
헤더를 확인하세요. Authorization: Bearer 뒤에 공백 하나와 키가 오고, 키에는 따옴표가 없어야 합니다. API 키 카드에서 변경을 선택했다면 이전 키는 더 이상 동작하지 않으므로 새 키를 복사하세요.
팀의 AuthToken이 보이지 않습니다
내 계정의 API 키를 사용하고 있습니다. 팀 대시보드로 전환하여 그곳에서 API 키를 복사하세요.
터널은 만들어졌는데 주소가 응답하지 않습니다
새 터널은 중지된 상태입니다. POST /tunnels/{tunnelId}/actions/start를 호출하고, 기기의 Localtonet 클라이언트가 사용한 AuthToken으로 실행 중인지 확인하세요.
429 Too Many Requests가 반환됩니다
요청에는 속도 제한이 있습니다. 잠시 기다린 후 요청을 다시 보내고, 개별 호출을 반복하는 대신 대량 요청 하나를 사용하세요.