Public API

Programmatically manage Mobile Proxy sub-users, set traffic limits, and track usage statistics with the Public API.

The Public API 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:

Method

Path

Description

POST

/login

Authenticate to get the access token (JWT).

GET

/users/{userId}/sub-users

Retrieve all active sub-users

POST

/users/{userId}/sub-users

Create a new sub-user.

GET

/users/{userId}/sub-users/{subUserId}

Retrieve traffic usage statistics for a specific sub-user.

PATCH

/users/{userId}/sub-users/{subUserId}

Modify a sub-user.

DELETE

/users/{userId}/sub-users/{subUserId}

Delete a sub-user.

GET

/users/{userId}/sub-users/{subUserId}/target-stats

Retrieve traffic usage statistics per target for a sub-user. Requires you to specify a date (last 30 days available).

GET

/users/{userId}/client-stats

Retrieve total traffic usage for the current month.

How to use the Public API

Testing through the web interface

1. Authorize your main user

If you're testing the functionality through the Public API interface, click the Authorize button.

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

The main user is the first sub-user in your users list.

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.

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

JWT expires in 1 hour. After that, you'll need to generate a new one.

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 or email.

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.

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.

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.

The main user is the first sub-user in your users list.

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

Header: Authorization: Basic base64(username:password)

curl -X "POST" \
  "https://residential-api.oxylabs.io/v2/login" \
  -H "accept: application/json" \
  -u "USERNAME:PASSWORD"

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 or email.

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.

Output example:

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

JWT expires in 1 hour. After that, you'll need to generate a new one.

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.

curl -X "GET" \
  "https://residential-api.oxylabs.io/v2/users/{userId}/client-stats" \
  -H "accept: application/json" \
  -H "Authorization: Bearer {token}"

Output sample

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

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: