# Public API

La [**Public API**](https://residential-api.oxylabs.io/v2/docs) te permite **gestionar usuarios de proxy de forma programática** sin usar el panel. Puedes crear, eliminar y modificar subusuarios de proxy, establecer límites de uso de tráfico y ver el uso de tráfico actual e histórico.

### Rutas disponibles

**Endpoint base:** `https://residential-api.oxylabs.io/v2`

Combina el endpoint base con la ruta para realizar acciones específicas:

<table data-full-width="false"><thead><tr><th width="99.15625">Método</th><th width="449.92578125">Ruta</th><th>Descripción</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>Autentícate para obtener el token de acceso (JWT).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Recuperar todos los subusuarios activos</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Crear un nuevo subusuario.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Recuperar estadísticas de uso de tráfico para un subusuario específico.</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Modificar un subusuario.</td></tr><tr><td><mark style="color:rojo;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Eliminar un subusuario.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>Recuperar estadísticas de uso de tráfico por destino para un subusuario. Requiere especificar una fecha (hay 30 días disponibles).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>Recuperar el uso total de tráfico del mes actual.</td></tr></tbody></table>

### Cómo usar la Public API

<details>

<summary><strong>Pruebas a través de la interfaz web</strong></summary>

#### 1. Autoriza a tu usuario principal

***

Si estás probando la funcionalidad a través de la [Public API](https://residential-api.oxylabs.io/v2/docs) interfaz, haz clic en el botón **Authorize** .

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FHDUkt8wgk877haEik6dv%2Fauthorize-1.png?alt=media&#x26;token=0eb8e049-9572-48e9-b7c5-ad4df83f6ca9" alt=""><figcaption></figcaption></figure>

Después, introduce las credenciales de tu usuario principal de proxy en la nueva ventana que se abre y selecciona **Authorize** una vez más.

{% hint style="info" %}
El usuario principal es el **primer subusuario** en tu [**lista de usuarios**](https://dashboard.oxylabs.io/?route=/overview/RP/users).
{% endhint %}

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FW1nXtD6tDkz1rC46YaSD%2Fauthorize-2.png?alt=media&#x26;token=eac5af9e-8f19-442e-95a3-4e7b69880b63" alt="" width="375"><figcaption></figcaption></figure>

#### 2. Inicia sesión para generar JWT

***

Después de la autorización, ve a la **POST** `/login` pestaña para generar el JSON Web Token (JWT) que se requiere para finalizar la autorización.

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2Fkm4CZbzi2BP2jFyhrKfe%2FJWT-1.png?alt=media&#x26;token=aa23d433-238d-48df-a9f7-dd4ce49bdbf0" alt=""><figcaption></figcaption></figure>

Luego, selecciona **Try it out** **→** **Execute**. Guarda los valores de `user_id` y `token` para usarlos después.

{% hint style="warning" %}
**El JWT expira en 1 hora**. Después de eso, tendrás que generar uno nuevo.
{% endhint %}

{% hint style="warning" %}
Si has cambiado recientemente la contraseña de tu usuario principal, recibirás un error. Para solucionarlo, debes **usar tu contraseña original** o **contactar a nuestro Equipo de Soporte 24/7** vía [chat en vivo ](https://oxylabs.drift.click/oxybot)o [correo electrónico](mailto:support@oxylabs.io).
{% endhint %}

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FKWgKi1NPpL672jraD09X%2FJWT-2.png?alt=media&#x26;token=49691976-637b-4b01-b8a4-2a67a386b7ce" alt=""><figcaption></figcaption></figure>

#### 3. Finaliza la autorización con JWT

***

Abre la ventana de **Authorization** de nuevo y **pega el token** del paso anterior en el campo de autenticación JWT Token. Luego, haz clic en el botón **Authorize** para guardar.

<figure><img src="https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FIUCqSyj5wrwWDmjRzPdC%2FJWT-3.png?alt=media&#x26;token=85de3d92-4180-4ca4-b3a8-9d609295e91c" alt="" width="435"><figcaption></figcaption></figure>

#### 4. Prueba la Public API

Ahora puedes probar los endpoints de la Public API en tu navegador. Para cada endpoint, deberás introducir el `user_id`, obtenido en el paso 2.

</details>

{% stepper %}
{% step %}

#### Inicia sesión y genera JWT

Usa la autenticación básica para iniciar sesión con las credenciales de tu usuario principal (codificadas en base64) y recibir un token JWT.

{% hint style="info" %}
El usuario principal es el **primer subusuario** en tu [**lista de usuarios**](https://dashboard.oxylabs.io/?route=/overview/RP/users)**.**
{% endhint %}

**Endpoint:** `https://residential-api.oxylabs.io/v2/login`

**Encabezado:** `Authorization: Basic base64(username:password)`

<pre class="language-bash"><code class="lang-bash">curl -X "POST" \\
  "https://residential-api.oxylabs.io/v2/login" \\
  -H "accept: application/json" \\
  -u "<a data-footnote-ref href="#user-content-fn-1">USERNAME:PASSWORD</a>"
</code></pre>

{% hint style="warning" %}
Si has cambiado recientemente la contraseña de tu usuario principal, recibirás un error. Para solucionarlo, debes **usar tu contraseña original** o **contactar a nuestro Equipo de Soporte 24/7** vía [chat en vivo ](https://oxylabs.drift.click/oxybot)o [correo electrónico](mailto:support@oxylabs.io).
{% endhint %}

Una vez ejecutado, el servidor responderá con **dos valores importantes** requeridos para los pasos posteriores:

* `user_id` es el identificador único de usuario requerido para las solicitudes de API.
* `token` es el JSON Web Token (JWT) requerido para la autorización posterior.

{% code title="Ejemplo de salida:" %}

```json
{
  "user_id": "00000000-0000-0000-0000-000000000000",
  "token": "example token"
}
```

{% endcode %}

{% hint style="warning" %}
**El JWT expira en 1 hora**. Después de eso, tendrás que generar uno nuevo.
{% endhint %}
{% endstep %}

{% step %}

#### Usa el `token` y `user_id` con solicitudes

Ahora puedes consultar la API para gestionar usuarios y verificar estadísticas. Todas las solicitudes posteriores requieren el JWT `token` y tu `user_id`.

**Encabezado:** `Authorization: Bearer {token}`

Por ejemplo, vamos a comprobar el uso total de tráfico del mes actual.

<pre class="language-bash" data-full-width="false"><code class="lang-bash">curl -X "GET" \\
  "https://residential-api.oxylabs.io/v2/users/<a data-footnote-ref href="#user-content-fn-2">{userId}</a>/client-stats" \\
  -H "accept: application/json" \\
  -H "Authorization: Bearer <a data-footnote-ref href="#user-content-fn-3">{token}</a>"
</code></pre>

<details>

<summary><strong>Ejemplo de salida</strong></summary>

```json
{
  "traffic": 1.2354839,
  "date_from": "2026-01-01",
  "date_to": "2026-01-15"
}
```

</details>
{% endstep %}
{% endstepper %}

### IPs de entrada de Backconnect

Si quieres usar tu propio nombre DNS del nodo de entrada de backconnect, puedes apuntar tu subdominio/dominio a nuestro nodo de entrada. Para hacerlo, debes añadir un registro DNS `CNAME` con `pr.oxylabs.io` como destino. Así es como se ve esta configuración en el gestor de DNS de Cloudflare para `el subdominio de entrada:` subdominio:

![Backconnect](https://338917265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FDpSfqieU6CUBFmCuS5mn%2Fcname.jpg?alt=media\&token=d9e18da6-2f2c-4858-ae91-da576c44b8eb)

Para más información, contacta con [**support@oxylabs.io**](mailto:support@oxylabs.io) o con tu gestor de cuenta.

[^1]: Reemplaza con las **credenciales de tu usuario principal**. cURL codifica automáticamente en base64 y usa el método de autenticación básica.

[^2]: Reemplaza con las `user_id`

[^3]: Reemplaza con tu JWT `token`