# Public API

The [**Public API**](https://residential-api.oxylabs.io/v2/docs) enables you to **manage proxy users programmatically** without using the dashboard. You can create, delete, and modify proxy sub-users, set traffic usage limits, and view current and historic traffic usage for Mobile Proxies.

### Available paths

**Base endpoint:** `https://residential-api.oxylabs.io/v2`

Combine the base endpoint with the path to perform specific actions:

<table data-full-width="false"><thead><tr><th width="99.15625">Method</th><th width="449.92578125">Path</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>Authenticate to get the access token (JWT).</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Retrieve all active sub-users</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Create a new sub-user.</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Retrieve traffic usage statistics for a specific sub-user.</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Modify a sub-user.</td></tr><tr><td><mark style="color:red;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Delete a sub-user.</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>Retrieve traffic usage statistics per target for a sub-user. Requires you to specify a date (last 30 days available).</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>Retrieve total traffic usage for the current month.</td></tr></tbody></table>

### How to use the Public API

<details>

<summary><strong>Testing through the web interface</strong></summary>

#### 1. Authorize your main user

***

If you're testing the functionality through the [Public API](https://residential-api.oxylabs.io/v2/docs) interface, click the **Authorize** button.

<figure><img src="https://63892162-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>

Next, enter your main proxy user's credentials in the newly opened window and select **Authorize** once again.

{% hint style="info" %}
The main user is the **first sub-user** in your [**users list**](https://dashboard.oxylabs.io/?route=/overview/MP/users).
{% endhint %}

<figure><img src="https://63892162-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. Log in to generate JWT

***

After authorization, navigate to the **POST** `/login` tab to generate the JSON Web Token (JWT) that's required to finalize authorization.

<figure><img src="https://63892162-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>

Then, select **Try it out** **→** **Execute**. Save the `user_id` and `token` values for later use.

{% hint style="warning" %}
**JWT expires in 1 hour**. After that, you'll need to generate a new one.
{% endhint %}

{% hint style="warning" %}
If you've changed your main user's password recently, you'll receive an error. To handle this, you must **use your original password** or **contact our 24/7 Support Team** via [live chat ](https://oxylabs.drift.click/oxybot)or [email](mailto:support@oxylabs.io).
{% endhint %}

<figure><img src="https://63892162-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. Finalize authorization with JWT

***

Open the **Authorization** window again and **paste the token** from the previous step in the JWT Token authentication field. Then, click the **Authorize** button to save.

<figure><img src="https://63892162-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. Test the Public API

You can now test the Public API endpoints in your browser. For every endpoint, you'll need to enter the `user_id`,  acquired in Step 2.

</details>

{% stepper %}
{% step %}

#### Log in and generate JWT

Use Basic Authentication to log in with your main user's credentials (encoded in base64) to receive a JWT token.

{% hint style="info" %}
The main user is the **first sub-user** in your [**users list**](https://dashboard.oxylabs.io/?route=/overview/MP/users)**.**
{% endhint %}

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

**Header:** `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" %}
If you've changed your main user's password recently, you'll receive an error. To handle this, you must **use your original password** or **contact our 24/7 Support Team** via [live chat ](https://oxylabs.drift.click/oxybot)or [email](mailto:support@oxylabs.io).
{% endhint %}

Once executed, the server will respond with **two important values** required for later steps:

* `user_id` is the unique user identifier required for API requests.
* `token` is the JSON Web Token (JWT) required for further authorization.

{% code title="Output example:" %}

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

{% endcode %}

{% hint style="warning" %}
**JWT expires in 1 hour**. After that, you'll need to generate a new one.
{% endhint %}
{% endstep %}

{% step %}

#### Use the `token` and `user_id` with requests

You can now query the API to manage users and check statistics. All subsequent requests require the JWT `token` and your `user_id`.

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

For example, let's check the total traffic usage for the current month.

<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>Output sample</strong></summary>

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

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

### Backonnect Entry IPs

If you want to use your own backconnect entry node DNS name, you can point your subdomain/domain to our entry node. To do that, you need to add a DNS `CNAME` record with `pr.oxylabs.io` as the target. This is how such setup looks on Cloudflare DNS manager for `entry` subdomain:

![Backconnect](https://63892162-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)

For more information, please contact [**support@oxylabs.io**](mailto:support@oxylabs.io) or your account manager.

[^1]: Replace with your **main user's credentials**. cURL automatically encodes to base64 and uses the Basic Authentication method.

[^2]: Replace with your `user_id`

[^3]: Replace with your JWT `token`