Public API

Gerencie programaticamente subusuários de Residential Proxies, defina limites de tráfego e acompanhe estatísticas de uso com a Public API.

A URL Public API 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.

Caminhos disponíveis

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

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

Método

Caminho

Descrição

POST

/login

Autentique-se para obter o token de acesso (JWT).

GET

/users/{userId}/sub-users

Recupere todos os subusuários ativos

POST

/users/{userId}/sub-users

Crie um novo subusuário.

GET

/users/{userId}/sub-users/{subUserId}

Recupere as estatísticas de uso de tráfego de um subusuário específico.

PATCH

/users/{userId}/sub-users/{subUserId}

Modifique um subusuário.

DELETE

/users/{userId}/sub-users/{subUserId}

Exclua um subusuário.

GET

/users/{userId}/sub-users/{subUserId}/target-stats

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

GET

/users/{userId}/client-stats

Recupere o uso total de tráfego do mês atual.

Como usar a Public API

Testando pela interface web

1. Autorize seu usuário principal

Se você estiver testando a funcionalidade pela Public API interface, clique no Autorizar botão.

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

O usuário principal é o primeiro subusuário na sua lista de usuários.

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.

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

O JWT expira em 1 hora. Depois disso, você precisará gerar um novo.

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 ou e-mail.

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.

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.

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.

O usuário principal é o primeiro subusuário na sua lista de usuários.

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

Cabeçalho: Authorization: Basic base64(username:password)

curl -X "POST" \
  "https://residential-api.oxylabs.io/v2/login" \
  -H "accept: application/json" \
  -u "USERNAME:PASSWORD"

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.

Exemplo de saída:

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

O JWT expira em 1 hora. Depois disso, você precisará gerar um novo.

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.

curl -X "GET" \
  "https://residential-api.oxylabs.io/v2/users/{userId}/client-stats" \
  -H "accept: application/json" \
  -H "Authorization: Bearer {token}"

Exemplo de saída

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

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: