> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/dai-li/mobile-proxies/public-api.md).

# 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>通过 Web 界面测试</strong></summary>

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

***

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

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

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

{% 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>

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

{% hint style="warning" %}
**JWT 在 1 小时后过期**。之后，您需要生成一个新的。
{% 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 完成授权

***

再次打开 **授权** 窗口，并将 **粘贴令牌** 从上一步获取的内容粘贴到 JWT Token 身份验证字段中。然后，点击 **授权** 按钮以保存。

<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 小时后过期**。之后，您需要生成一个新的。
{% 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 管理器中为 `entry` 子域名进行此类设置的样子：

![Backconnect](/files/15725c30595c5f6f27a325bd3864394be99f333c)

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

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

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

[^3]: 替换为您的 JWT `token`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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