Register & Manage Agents - VerifiedProxy Docs

On this page

Registering an Agent Agent Properties Scopes Viewing Agents Managing Multiple Agents

Registering an Agent

You can register agents using the CLI (recommended) or the API directly.

Option A: Via CLI (Recommended)

terminal

npx verifiedproxy install

The interactive installer will walk you through:

API URL (defaults to https://app.verifiedproxy.com)
Your organization API key
Agent name (e.g., "Acme Research Bot")
Scopes as comma-separated list (e.g., browse,data-collect)
Local proxy port (default: 8099)

Option B: Via API

curl

curl -X POST https://app.verifiedproxy.com/api/agents/register \
  -H "Authorization: Bearer vp_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Research Bot",
    "scopes": ["browse", "data-collect"]
  }'

200 OK

json

{
  "agent_id": "ag_a1b2c3d4",
  "agent_secret": "vp_ag_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "name": "Acme Research Bot",
  "scopes": ["browse", "data-collect"]
}

🔒

Save the agent_secret immediately. It is returned only once and cannot be retrieved later. The secret is hashed before storage.

Agent Properties

agent_id string Unique identifier prefixed with ag_. Public — safe to share and include in headers.
agent_secret string Private credential prefixed with vp_ag_. Used only by the local proxy to create sessions. Never sent to websites.
name string Human-readable name for this agent (e.g., "Acme Research Bot").
scopes string[] List of permissions declaring what the agent is authorized to do.
status enum active or revoked. Revoked agents cannot create sessions or pass verification.

Scopes

Scopes are strings that declare what your agent is authorized to do. Websites can check these scopes to make access decisions. Common scopes include:

Scope	Description
`browse`	Read and navigate web pages
`form-fill`	Submit forms on behalf of the user
`data-collect`	Collect and aggregate data from pages

ℹ️

Scopes are self-declared and informational. They tell websites what your agent intends to do. Websites decide how to act on this information (allow, restrict, or customize behavior).

Viewing Agents

All agents registered under your organization appear on the dashboard at:

url

https://app.verifiedproxy.com/dashboard

The dashboard shows each agent's ID, scopes, status, and creation date.

Get Agent Profile (Public)

Anyone can look up an agent's public profile:

curl

curl https://app.verifiedproxy.com/api/agents/ag_a1b2c3d4

200 OK

json

{
  "agent_id": "ag_a1b2c3d4",
  "name": "Acme Research Bot",
  "org_name": "Acme Corp",
  "scopes": ["browse", "data-collect"],
  "status": "active"
}

Managing Multiple Agents

You can register as many agents as you need under a single organization. Each agent gets its own credentials and can have different scopes.

example

# Register a browsing-only agent
curl -X POST https://app.verifiedproxy.com/api/agents/register \
  -H "Authorization: Bearer $VP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Read-Only Bot", "scopes": ["browse"]}'

# Register a data-collection agent
curl -X POST https://app.verifiedproxy.com/api/agents/register \
  -H "Authorization: Bearer $VP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Research Agent", "scopes": ["browse", "data-collect"]}'