# Public API

O [**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 visualizar o uso de tráfego atual e histórico.

### 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 do 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="https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FHDUkt8wgk877haEik6dv%2Fauthorize-1.png?alt=media&#x26;token=0eb8e049-9572-48e9-b7c5-ad4df83f6ca9" alt=""><figcaption></figcaption></figure>

Em seguida, insira as credenciais do seu usuário principal de proxy na janela que abrir 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/RP/users).
{% endhint %}

<figure><img src="https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FW1nXtD6tDkz1rC46YaSD%2Fauthorize-2.png?alt=media&#x26;token=eac5af9e-8f19-442e-95a3-4e7b69880b63" alt="" width="375"><figcaption></figcaption></figure>

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

***

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

<figure><img src="https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2Fkm4CZbzi2BP2jFyhrKfe%2FJWT-1.png?alt=media&#x26;token=aa23d433-238d-48df-a9f7-dd4ce49bdbf0" alt=""><figcaption></figcaption></figure>

Em seguida, selecione **Try it out** **→** **Execute**. Salve os valores de `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ê alterou a senha do seu usuário principal recentemente, você receberá um erro. Para resolver 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="https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FKWgKi1NPpL672jraD09X%2FJWT-2.png?alt=media&#x26;token=49691976-637b-4b01-b8a4-2a67a386b7ce" 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="https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FIUCqSyj5wrwWDmjRzPdC%2FJWT-3.png?alt=media&#x26;token=85de3d92-4180-4ca4-b3a8-9d609295e91c" 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) 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/RP/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 a senha do seu usuário principal recentemente, você receberá um erro. Para resolver 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 %}

Depois de executado, o servidor responderá com **dois valores importantes** necessários para as etapas seguintes:

* `user_id` é o identificador exclusivo do usuário necessário para as solicitações da API.
* `token` é o JSON Web Token (JWT) necessário para autorização adicional.

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

### Backonnect Entry IPs

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

![Backconnect](https://1214208351-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FDpSfqieU6CUBFmCuS5mn%2Fcname.jpg?alt=media\&token=d9e18da6-2f2c-4858-ae91-da576c44b8eb)

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

[^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 seu `user_id`

[^3]: Substitua pelo seu JWT `token`