circle-check
Documentation has been updated: see help center and changelog in one place.
search
Oxylabs dashboardContact us

Public API

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

The Public APIarrow-up-right 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.

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

hashtag
How to use the Public API

chevron-rightTesting through the web interfacehashtag

hashtag
1. Authorize your main user

If you're testing the functionality through the Public APIarrow-up-right interface, click the Authorize button.

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

circle-info

The main user is the first sub-user in your users listarrow-up-right.

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

circle-exclamation

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

circle-exclamation

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 arrow-up-rightor emailenvelope.

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

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

1

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

circle-info

The main user is the first sub-user in your users listarrow-up-right.

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"
circle-exclamation

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 arrow-up-rightor emailenvelope.

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"
}
circle-exclamation

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

2

hashtag
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}"
chevron-rightOutput samplehashtag
{
  "traffic": 1.2354839,
  "date_from": "2026-01-01",
  "date_to": "2026-01-15"
}

hashtag
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

For more information, please contact [email protected]envelope or your account manager.

PreviousRestricted TargetsNextResponse Codes

Last updated

Was this helpful?