# 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.

### 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="/files/HIe9nbPveRKYBir3lMyg" 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/RP/users).
{% endhint %}

<figure><img src="/files/GJgKNofGQIs4kbGfPCsa" 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="/files/EOogzclag8MJka3MeGSp" 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="/files/TmeJa7vHOiowSwtWLVwR" 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="/files/eoO4OdI4IuLHHn254DSH" 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/RP/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](/files/5tt6VuASGsfDW3uhc57P)

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`


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.