Ctrlk
Access Oxylabs dashboardContact us
x-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Public API

通过 Public API 以编程方式管理住宅代理子用户、设置流量限制并跟踪使用统计数据。

该 Public API 使你能够 以编程方式管理代理用户 无需使用仪表板。你可以创建、删除和修改代理子用户，设置流量使用上限，并查看当前和历史流量使用情况。

可用路径

基础端点： https://residential-api.oxylabs.io/v2

将基础端点与路径结合以执行特定操作：

方法
路径
描述

POST

/login

进行身份验证以获取访问令牌（JWT）。

GET

/users/{userId}/sub-users

获取所有活跃子用户

POST

/users/{userId}/sub-users

创建一个新的子用户。

GET

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

获取特定子用户的流量使用统计信息。

PATCH

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

修改一个子用户。

DELETE

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

删除一个子用户。

GET

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

获取某个子用户按目标划分的流量使用统计信息。需要指定日期（可查看最近 30 天）。

GET

/users/{userId}/client-stats

获取当月总流量使用情况。

如何使用 Public API

通过网页界面进行测试

1. 授权你的主用户

如果你正在通过 Public API 界面进行测试，请点击 授权 按钮。

接下来，在新打开的窗口中输入你的主代理用户凭据并 授权 再次选择。

主用户是 第一个子用户 在你的 用户列表中.

2. 登录以生成 JWT

授权后，前往 POST /login 选项卡以生成完成授权所需的 JSON Web Token (JWT)。

然后，选择 试用 → 执行. 保存 user_id 和 token 值以供后续使用。

JWT 在 1 小时后过期. 之后，你需要重新生成一个。

如果你最近更改了主用户的密码，你会收到错误。要处理此问题，你必须 使用原始密码 还是 联系我们的 7x24 支持团队 通过 在线聊天 还是 电子邮件.

3. 使用 JWT 完成授权

再次打开 授权 窗口并 粘贴令牌 到 JWT Token 认证字段中。然后，点击 授权 按钮保存。

4. 测试 Public API

现在你可以在浏览器中测试 Public API 端点。对于每个端点，你都需要输入 user_id，即在第 2 步中获取的内容。

1

登录并生成 JWT

使用 Basic Authentication，用你的主用户凭据（以 base64 编码）登录以获取 JWT 令牌。

主用户是 第一个子用户 在你的 用户列表中.

端点： https://residential-api.oxylabs.io/v2/login

标头： Authorization: Basic base64(username:password)

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

如果你最近更改了主用户的密码，你会收到错误。要处理此问题，你必须 使用原始密码 还是 联系我们的 7x24 支持团队 通过 在线聊天 还是 电子邮件.

执行后，服务器将返回 两个重要值 供后续步骤使用：

  • user_id 是 API 请求所需的唯一用户标识符。

  • token 是进一步授权所需的 JSON Web Token (JWT)。

输出示例：
{
  "user_id": "00000000-0000-0000-0000-000000000000",
  "token": "example token"
}

JWT 在 1 小时后过期. 之后，你需要重新生成一个。

2

使用 token 和 user_id 在请求中

你现在可以查询 API 来管理用户并检查统计信息。后续所有请求都需要 JWT token 以及你的 user_id.

标头： Authorization: Bearer {token}

例如，让我们检查当月总流量使用情况。

curl -X "GET" \
  "https://residential-api.oxylabs.io/v2/users/{userId}/client-stats" \
  -H "accept: application/json" \
  -H "Authorization: Bearer {token}"
输出示例
{
  "traffic": 1.2354839,
  "date_from": "2026-01-01",
  "date_to": "2026-01-15"
}

Backconnect 入口 IP

如果你想使用自己的 backconnect 入口节点 DNS 名称，可以将你的子域名/域名指向我们的入口节点。为此，你需要添加一条 DNS CNAME 记录，并将 pr.oxylabs.io 作为目标。这是在 Cloudflare DNS 管理器中针对 入口 子域名：

Backconnect

如需更多信息，请联系 support@oxylabs.io 或你的客户经理。

上一页响应代码
下一页移动代理

这有帮助吗？