# Public API

该 [**Public API**](https://residential-api.oxylabs.io/v2/docs) 使您能够 **以编程方式管理代理用户** 无需使用仪表板。您可以创建、删除和修改代理子用户，设置流量使用限制，并查看移动代理的当前和历史流量使用情况。

### 可用路径

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

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

<table data-full-width="false"><thead><tr><th width="99.15625">方法</th><th width="449.92578125">路径</th><th>描述</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>进行身份验证以获取访问令牌（JWT）。</td></tr><tr><td><mark style="color:蓝色;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>检索所有活跃子用户</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>创建一个新的子用户。</td></tr><tr><td><mark style="color:蓝色;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>检索特定子用户的流量使用统计信息。</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>修改子用户。</td></tr><tr><td><mark style="color:红色;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>删除子用户。</td></tr><tr><td><mark style="color:蓝色;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>检索某个子用户按目标划分的流量使用统计信息。需要您指定日期（可查看最近30天）。</td></tr><tr><td><mark style="color:蓝色;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>检索当月总流量使用情况。</td></tr></tbody></table>

### 如何使用 Public API

<details>

<summary><strong>通过网页界面进行测试</strong></summary>

#### 1. 授权您的主用户

***

如果您正在通过 [Public API](https://residential-api.oxylabs.io/v2/docs) 界面测试此功能，请点击 **Authorize** 按钮。

<figure><img src="/files/10c1e0b6c142762f38c76be8006d59bd7981e69e" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
主用户是您的 **第一个子用户** 中的 [**用户列表**](https://dashboard.oxylabs.io/?route=/overview/MP/users).
{% endhint %}

<figure><img src="/files/8d50b2d510019ce3b6a85fd0c7e0bb59a4da9e3c" alt="" width="375"><figcaption></figcaption></figure>

#### 2. 登录以生成 JWT

***

授权后，导航到 **POST** `/login` 选项卡以生成完成授权所需的 JSON Web Token（JWT）。

<figure><img src="/files/d7b0524b758cd88dff8e10d6771e3c15f252dae1" alt=""><figcaption></figcaption></figure>

然后，选择 **Try it out** **→** **Execute**。保存 `user_id` 和 `token` 值以供后续使用。

{% hint style="warning" %}
**JWT 的有效期为 1 小时**。之后，您需要生成新的 JWT。
{% endhint %}

{% hint style="warning" %}
如果您最近更改了主用户的密码，您会收到错误。要处理此问题，您必须 **使用原始密码** 或 **通过** 联系我们 24/7 支持团队 [在线聊天 ](https://oxylabs.drift.click/oxybot)或 [电子邮件](mailto:support@oxylabs.io).
{% endhint %}

<figure><img src="/files/2a10b8069f1fdc4c58381a8bf1965d281f298561" alt=""><figcaption></figcaption></figure>

#### 3. 使用 JWT 完成授权

***

再次打开 **Authorization** 窗口，并将 **令牌粘贴** 到 JWT Token 身份验证字段中。然后，点击 **Authorize** 按钮保存。

<figure><img src="/files/7f044b336be225b84624c4399ba33d694e6a5709" alt="" width="435"><figcaption></figcaption></figure>

#### 4. 测试 Public API

现在您可以在浏览器中测试 Public API 端点。对于每个端点，您都需要输入 `user_id`，该值在第 2 步中获取。

</details>

{% stepper %}
{% step %}

#### 登录并生成 JWT

使用基本身份验证通过主用户的凭据登录（以 base64 编码）以接收 JWT 令牌。

{% hint style="info" %}
主用户是您的 **第一个子用户** 中的 [**用户列表**](https://dashboard.oxylabs.io/?route=/overview/MP/users)**.**
{% endhint %}

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

**请求头：** `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" %}
如果您最近更改了主用户的密码，您会收到错误。要处理此问题，您必须 **使用原始密码** 或 **通过** 联系我们 24/7 支持团队 [在线聊天 ](https://oxylabs.drift.click/oxybot)或 [电子邮件](mailto:support@oxylabs.io).
{% endhint %}

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

* `user_id` 是 API 请求所需的唯一用户标识符。
* `token` 是后续授权所需的 JSON Web Token（JWT）。

{% code title="输出示例：" %}

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

{% endcode %}

{% hint style="warning" %}
**JWT 的有效期为 1 小时**。之后，您需要生成新的 JWT。
{% endhint %}
{% endstep %}

{% step %}

#### 使用 `token` 和 `user_id` 配合请求

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

**请求头：** `Authorization: Bearer {token}`

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

<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>输出样本</strong></summary>

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

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

### Backonnect 入口 IP

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

![Backconnect](/files/15725c30595c5f6f27a325bd3864394be99f333c)

如需更多信息，请联系 [**support@oxylabs.io**](mailto:support@oxylabs.io) 或您的客户经理。

[^1]: 替换为您的 **主用户凭据**。cURL 会自动编码为 base64，并使用基本身份验证方法。

[^2]: 替换为您的 `user_id`

[^3]: 替换为您的 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/products/cn/dai-li/mobile-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.