> 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/pt-br/proxies/mobile-proxies/public-api.md).

# Public API

A URL [**Public API**](https://residential-api.oxylabs.io/v2/docs) permite que você **gerencie usuários de proxy programaticamente** sem usar o painel. Você pode criar, excluir e modificar subusuários de proxy, definir limites de uso de tráfego e ver o uso de tráfego atual e histórico para Mobile Proxies.

### Caminhos disponíveis

**Endpoint base:** `https://residential-api.oxylabs.io/v2`

Combine o endpoint base com o caminho para realizar ações específicas:

<table data-full-width="false"><thead><tr><th width="99.15625">Método</th><th width="449.92578125">Caminho</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>Autentique-se para obter o token de acesso (JWT).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Recupere todos os subusuários ativos</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Crie um novo subusuário.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Recupere as estatísticas de uso de tráfego de um subusuário específico.</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Modifique um subusuário.</td></tr><tr><td><mark style="color:vermelho;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Exclua um subusuário.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>Recupere as estatísticas de uso de tráfego por destino para um subusuário. É necessário especificar uma data (últimos 30 dias disponíveis).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>Recupere o uso total de tráfego do mês atual.</td></tr></tbody></table>

### Como usar a Public API

<details>

<summary><strong>Testando pela interface web</strong></summary>

#### 1. Autorize seu usuário principal

***

Se você estiver testando a funcionalidade pela [Public API](https://residential-api.oxylabs.io/v2/docs) interface, clique no **Autorizar** botão.

<figure><img src="/files/7ad4c79478dc8cec2d4d6c347a1b9f827c665a6d" alt=""><figcaption></figcaption></figure>

Em seguida, insira as credenciais do seu usuário principal de proxy na janela recém-aberta e selecione **Autorizar** novamente.

{% hint style="info" %}
O usuário principal é o **primeiro subusuário** na sua [**lista de usuários**](https://dashboard.oxylabs.io/?route=/overview/MP/users).
{% endhint %}

<figure><img src="/files/7588634d33de426f4ed69f616d4a519a26f1ca70" alt="" width="375"><figcaption></figcaption></figure>

#### 2. Faça login para gerar o JWT

***

Após a autorização, navegue até a **POST** `/login` guia para gerar o JSON Web Token (JWT) necessário para finalizar a autorização.

<figure><img src="/files/7bd2f4e29c12c2024adc14a80d69aa5c199d8a6c" alt=""><figcaption></figcaption></figure>

Depois, selecione **Experimentar** **→** **Executar**. Salve os `user_id` e `token` valores para uso posterior.

{% hint style="warning" %}
**O JWT expira em 1 hora**. Depois disso, você precisará gerar um novo.
{% endhint %}

{% hint style="warning" %}
Se você alterou recentemente a senha do seu usuário principal, você receberá um erro. Para lidar com isso, você deve **usar sua senha original** ou **contatar nossa equipe de suporte 24/7** via [chat ao vivo ](https://oxylabs.drift.click/oxybot)ou [e-mail](mailto:support@oxylabs.io).
{% endhint %}

<figure><img src="/files/4f37b3c8eb30d4e21630d3b42ae6103c131e44bf" alt=""><figcaption></figcaption></figure>

#### 3. Finalize a autorização com JWT

***

Abra a **Autorização** janela novamente e **cole o token** da etapa anterior no campo de autenticação do Token JWT. Depois, clique no **Autorizar** botão para salvar.

<figure><img src="/files/37e3488bd5f952d4fc8204f8433057ba60750763" alt="" width="435"><figcaption></figcaption></figure>

#### 4. Teste a Public API

Agora você pode testar os endpoints da Public API no seu navegador. Para cada endpoint, você precisará inserir o `user_id`, obtido na Etapa 2.

</details>

{% stepper %}
{% step %}

#### Faça login e gere o JWT

Use a autenticação básica para fazer login com as credenciais do seu usuário principal (codificadas em base64) para receber um token JWT.

{% hint style="info" %}
O usuário principal é o **primeiro subusuário** na sua [**lista de usuários**](https://dashboard.oxylabs.io/?route=/overview/MP/users)**.**
{% endhint %}

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

**Cabeçalho:** `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" %}
Se você alterou recentemente a senha do seu usuário principal, você receberá um erro. Para lidar com isso, você deve **usar sua senha original** ou **contatar nossa equipe de suporte 24/7** via [chat ao vivo ](https://oxylabs.drift.click/oxybot)ou [e-mail](mailto:support@oxylabs.io).
{% endhint %}

Após a execução, o servidor responderá com **dois valores importantes** necessários para as etapas seguintes:

* `user_id` é o identificador único do usuário necessário para solicitações de API.
* `token` é o JSON Web Token (JWT) necessário para autorização posterior.

{% code title="Exemplo de saída:" %}

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

{% endcode %}

{% hint style="warning" %}
**O JWT expira em 1 hora**. Depois disso, você precisará gerar um novo.
{% endhint %}
{% endstep %}

{% step %}

#### Use o `token` e `user_id` com solicitações

Agora você pode consultar a API para gerenciar usuários e verificar estatísticas. Todas as solicitações subsequentes exigem o JWT `token` e o seu `user_id`.

**Cabeçalho:** `Authorization: Bearer {token}`

Por exemplo, vamos verificar o uso total de tráfego do mês atual.

<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>Exemplo de saída</strong></summary>

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

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

### IPs de entrada do Backonnect

Se você quiser usar o nome DNS do seu próprio nó de entrada backconnect, pode apontar seu subdomínio/domínio para o nosso nó de entrada. Para isso, você precisa adicionar um registro DNS `CNAME` com `pr.oxylabs.io` como destino. Veja como essa configuração aparece no gerenciador DNS da Cloudflare para `entrada` subdomínio:

![Backconnect](/files/208393b420a11d326902f336f0a75c88312bb61d)

Para mais informações, entre em contato com [**support@oxylabs.io**](mailto:support@oxylabs.io) ou com seu gerente de conta.

[^1]: Substitua pelas credenciais do **seu usuário principal**. O cURL codifica automaticamente em base64 e usa o método de Autenticação Básica.

[^2]: Substitua pelas credenciais do `user_id`

[^3]: Substitua pelo seu 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, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/proxies/mobile-proxies/public-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.