Litport API

Litport API da a una integración acceso a tus propios tokens, paquetes y datos de pago por GB (PPG). Puede crear, cambiar y eliminar proxies de pago por GB, con un tope de tráfico y una caducidad para cada uno, y volver a emitir las credenciales de cualquier proxy que tengas. Lee el uso de muchos proxies a la vez y cambia la ubicación del token, la rotación, la IP nueva y las IP permitidas del paquete. Úsala para revender proxies o dar a cada miembro del equipo o herramienta el suyo: crea un proxy de pago por GB por cliente, pon un tope a su tráfico y lee el uso de muchos proxies a la vez.

URL base:

https://litport.net/api/v1

Los perfiles de VPN se crean en el panel; la API todavía no puede crearlos ni cambiarlos. Consulta Acceso VPN.

Áreas#

Autenticación#

Crea una clave de API en Configuración. Su valor completo sigue disponible allí después de crearla o rotarla.

export LITPORT_API_KEY='lit_replace_with_your_key'
curl 'https://litport.net/api/v1/tokens' \
  -H "Authorization: Bearer $LITPORT_API_KEY"

Los clientes externos usan exactamente el esquema Bearer. No envíes una clave en la cadena de consulta, el cuerpo JSON, una cookie ni el usuario del proxy. Guárdala como un secreto, restringe el acceso a cargas de trabajo del lado del servidor y rótala si pudo filtrarse.

Los controles Ejecutar de estas páginas de documentación usan tu cuenta de Litport con la sesión iniciada, solo para solicitudes GET. Toda escritura necesita una clave de API Bearer.

Alcance de cada credencial#

Reglas comunes de la API#

Todos los endpoints de todas las áreas siguen las mismas reglas, así que una integración las aprende una sola vez.

Identificadores. Usa los tokenId y packageId numéricos públicos. Selecciona un pool de pago por GB por su authKey y una IP permitida por la propia IP. Ningún endpoint recibe ni devuelve un ID de base de datos.

Nombres. Los campos van en camelCase. Los valores enumerados nuevos y los slugs van en kebab-case en minúsculas, por ejemplo awaiting-payment, more-allowed-ips, package-inactive. Los códigos de error siguen en UPPER_SNAKE. El texto libre (etiquetas, credenciales, nombres de pools) no tiene restricciones. Unos pocos valores conservan su escritura actual en lugar de renombrarse para coincidir: trafficBasis: "customer_chargeable" y timezone: "UTC" en los datos de uso, y los valores type/status de los tokens.

Valores. Las fechas y horas son ISO-8601 en UTC y terminan en Z. Los recuentos grandes de bytes son cadenas decimales, no números JSON, para que un cliente nunca pierda precisión.

Formas de respuesta. Un objeto único es {"data": {...}}. Un endpoint que devuelve una lista siempre responde {"data": [...], "page": {"nextCursor": ...}}. Hay dos tipos de lista:

• una lista paginada (GET /tokens, GET /usage, GET /packages, GET /pay-per-gb/geo) acepta limit y cursor;
• una lista completa (GET /pay-per-gb/pools, GET /tokens/{tokenId}/location/options) siempre devuelve todos los elementos, no acepta limit ni cursor e informa page.nextCursor: null.

Un array dentro de un objeto, como los buckets del uso, las ips de las IP permitidas o los tokenIds de un paquete, es un campo ordinario, no una lista de endpoint. GET /usage es una lista paginada cuyo data es un objeto: el range y los proxies en data.tokens.

Paginación. limit va de 1 a 100, con 50 de forma predeterminada. cursor es el page.nextCursor de la respuesta anterior, reenviado sin cambios; trátalo como opaco. Un limit incorrecto es 400 INVALID_LIMIT; un cursor incorrecto o ajeno es 400 INVALID_CURSOR. Sigue solicitando page.nextCursor hasta que sea null.

Errores. Todo error es {"error": {"code", "message", "requestId", "docsUrl", "retryable"}}, más nextChangeAt cuando se aplica una espera. retryable indica si la misma solicitud, enviada de nuevo, puede tener éxito y se puede enviar sin riesgo. Consulta Errores de la API para ver la tabla completa de estados y un apartado de detalle por cada código.

Escrituras. Toda escritura necesita una clave de API Bearer; una sesión iniciada en la documentación solo puede leer. Envía un cuerpo JSON cuando el endpoint lo tenga. No hay encabezado de precondición: prevalece la última escritura confirmada. Toda escritura se puede repetir sin riesgo, salvo POST /tokens/{tokenId}/new-ip en un token estático (en uno rotativo, repetirla solo da otra IP), POST /tokens sin un externalRef (una repetición puede crear un segundo proxy), POST /tokens/{tokenId}/credentials sin un requestId (una repetición emite otro par) y PUT /tokens/{tokenId}/location con {"random": true} (una repetición puede volver a mover el proxy). Envía un externalRef con cada creación y un requestId con cada reemisión que quizá debas reintentar; consulta Crear y administrar proxies.

Límites de frecuencia#

Se aplican tres límites, todos informados mediante encabezados estándar.

• 120 solicitudes cada 60 segundos, por clave de API, lecturas y escrituras juntas. Superarlo da 429 RATE_LIMITED.
• 10 lecturas de la lista de uso (GET /usage) cada 60 segundos, por clave de API. El límite por clave se comprueba primero; una solicitud que pasa esa comprobación y es una lectura de la lista de uso comprueba después este límite e informa en su lugar los encabezados de ese limitador.
• 20 escrituras de IP permitidas cada 60 segundos, por paquete (PUT/DELETE /packages/{packageId}/allowed-ips…). El límite por clave se comprueba primero; una solicitud que pasa esa comprobación y además es una escritura de IP permitidas comprueba después el límite del paquete e informa en su lugar los encabezados de ese limitador.

Lee RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset en cada respuesta; una solicitud rechazada incluye además Retry-After.

Convenciones#

• Las respuestas son JSON.
• X-Request-ID identifica la solicitud; inclúyelo cuando informes de un fallo.
• Las respuestas autenticadas incluyen Cache-Control: private, no-store y Vary: Authorization.
• Esta API no usa ETags ni precondiciones If-Match en ningún punto.

Contrato legible por máquinas#

Usa el documento OpenAPI 3.1 para cada ruta, parámetro, cuerpo de solicitud y esquema de respuesta. Gestiona el envoltorio de error antes de usar los datos de cada endpoint.