> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/proxies/residential-proxies/public-api.md).

# Public API

Gestiona programáticamente subusuarios de Residential Proxies, establece límites de tráfico y sigue las estadísticas de uso con la Public API.

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

### Rutas disponibles

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

Combine el punto final 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>Autenticarse 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 (disponible para los últimos 30 días).</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. Autorice a su usuario principal

***

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

<figure><img src="https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-22e213b85d803819672eefc9b304c22d4320f603%2Fauthorize-1.png?alt=media" alt=""><figcaption></figcaption></figure>

A continuación, introduzca las credenciales de su usuario proxy principal en la ventana que se abre y seleccione **Autorizar** una vez más.

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

<figure><img src="https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-433b36c6ead11efb109315877279802db64aa636%2Fauthorize-2.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

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

***

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

<figure><img src="https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-35156ad8c2232a46b7850229ed203bb5af77e4b4%2FJWT-1.png?alt=media" alt=""><figcaption></figcaption></figure>

Luego, seleccione **Probar** **→** **Ejecutar**. Guarde los `user_id` y `token` valores para usarlos más adelante.

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

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

<figure><img src="https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-78bf728799910d6d33c6fbccaa6253bf4e92c31c%2FJWT-2.png?alt=media" alt=""><figcaption></figcaption></figure>

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

***

Abra la ventana de **Autorización** de nuevo y **pegue el token** del paso anterior en el campo de autenticación JWT Token. Luego, haga clic en el **Autorizar** botón para guardar.

<figure><img src="https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-9d3696e13a42aae79ece4d54b8346040682b936c%2FJWT-3.png?alt=media" alt="" width="435"><figcaption></figcaption></figure>

#### 4. Pruebe la Public API

Ahora puede probar los endpoints de Public API en su navegador. Para cada endpoint, deberá ingresar el `user_id`, obtenido en el Paso 2.

</details>

{% stepper %}
{% step %}

#### Inicie sesión y genere JWT

Use Autenticación Básica para iniciar sesión con las credenciales de su usuario principal (codificadas en base64) y recibir un token JWT.

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

**Punto final:** `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 ha cambiado recientemente la contraseña de su usuario principal, recibirá un error. Para solucionarlo, debe **usar su contraseña original** o **contactar a nuestro equipo de soporte 24/7** a través de [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** necesarios para los pasos posteriores:

* `user_id` es el identificador único de usuario requerido para las solicitudes de API.
* `token` es el token web JSON (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, deberá generar uno nuevo.
{% endhint %}
{% endstep %}

{% step %}

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

Ahora puede consultar la API para administrar usuarios y verificar estadísticas. Todas las solicitudes posteriores requieren el JWT `token` y su `user_id`.

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

Por ejemplo, comprobemos 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 Backonnect

Si desea usar el nombre DNS de su propio nodo de entrada backconnect, puede apuntar su subdominio/dominio a nuestro nodo de entrada. Para hacerlo, debe agregar un registro DNS `CNAME` con `pr.oxylabs.io` como destino. Así es como se ve una configuración de este tipo en el administrador DNS de Cloudflare para `entrada` subdominio:

![Backconnect](https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-9d15ff608e52a76e6d288eb45c3bd648ddf970ef%2Fcname.jpg?alt=media)

Para más información, póngase en contacto con [**support@oxylabs.io**](mailto:support@oxylabs.io) o con su administrador de cuenta.

[^1]: Sustituya por las credenciales de su **usuario principal**. cURL codifica automáticamente en base64 y usa el método de Autenticación Básica.

[^2]: Sustituya por las credenciales de su `user_id`

[^3]: Sustituya por su JWT `token`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/es/proxies/residential-proxies/public-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.