# Public API

A [**Public API**](https://residential-api.oxylabs.io/v2/docs) permite que você **gerencie usuários proxy programaticamente** sem usar o painel. Você pode criar, excluir e modificar subusuários de proxy, definir limites de uso de tráfego e visualizar 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 executar 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>Recuperar 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>Criar 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>Recuperar estatísticas de uso de tráfego para 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>Modificar um subusuário.</td></tr><tr><td><mark style="color:vermelho;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Excluir 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>Recuperar estatísticas de uso de tráfego por destino para um subusuário. Requer que você especifique 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>Recuperar o uso total de tráfego para o mês atual.</td></tr></tbody></table>

### Como usar a Public API

<details>

<summary><strong>Teste 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 botão **Authorize** .

<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 **Authorize** 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 JWT

***

Após a autorização, navegue até a aba **POST** `/login` 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 **Try it out** **→** **Execute**. Salve os valores `user_id` e `token` 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ê tiver alterado recentemente a senha do seu usuário principal, você receberá um erro. Para resolver isso, você deve **usar sua senha original** ou **entrar em contato com 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 janela **Authorization** novamente e **cole o token** da etapa anterior no campo de autenticação JWT Token. Em seguida, clique no botão **Authorize** 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 JWT

Use a Autenticação Básica para fazer login com as credenciais do seu usuário principal (codificadas em base64) e 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ê tiver alterado recentemente a senha do seu usuário principal, você receberá um erro. Para resolver isso, você deve **usar sua senha original** ou **entrar em contato com nossa equipe de Suporte 24/7** via [chat ao vivo ](https://oxylabs.drift.click/oxybot)ou [e-mail](mailto:support@oxylabs.io).
{% endhint %}

Uma vez executado, o servidor responderá com **dois valores importantes** necessários para as etapas posteriores:

* `user_id` é o identificador exclusivo do usuário necessário para solicitações da 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 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, você pode apontar seu subdomínio/domínio para nosso nó de entrada. Para fazer isso, você precisa adicionar um registro DNS `CNAME` com `pr.oxylabs.io` como destino. Veja como essa configuração aparece no gerenciador de DNS da Cloudflare para `subdomínio de` entrada:

![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 para base64 e usa o método de Autenticação Básica.

[^2]: Substitua pelas `user_id`

[^3]: Substitua pelo seu 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/pt-br/proxies/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.