Authentication

All API requests require an API key.

Get your API key

Go to Settings → API after creating an account.

Create keys programmatically

You can also mint, list, rotate and delete keys over the API. An existing API key is enough to create another one — you do not need a dashboard session.

authenticated

Creates a key. Optional body {"name": "My Key"}; the name defaults to API Key.

curl -X POST https://virtualsms.io/api/v1/keys/generate \
  -H "x-api-key: YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-prod"}'

{
  "success": true,
  "api_key": "vsms_9f2ac41b...",
  "key_id": "7b3d0c48-2e91-4a65-bf07-19d4c6a83f22",
  "name": "agent-prod",
  "note": "Save this key — it cannot be retrieved again."
}

api_key is shown once, in this 201 response. Only a hash is stored, so nothing can recover it later. Keys are prefixed vsms_.

Method	Path	Does
`POST`	`/api/v1/keys/generate`	Create a key — returns it once
`GET`	`/api/v1/keys`	List your keys: `id`, `key_prefix`, `name`, `last_used_at`, `created_at`, `is_active`. Never the key itself
`POST`	`/api/v1/keys/{id}/rotate`	Issue a new secret for the same key record — the old value stops working immediately
`DELETE`	`/api/v1/keys/{id}`	Delete the key permanently

A rotate or delete against a key you do not own returns 404. An autonomous agent can fund itself and receive a working API key without a human creating an account — no signup form, no card, no dashboard. POST /api/v1/x402/topup returns HTTP 402 Payment Required with a machine-readable payment manifest. The agent pays the requested stablecoin amount and retries; the response contains an api_key and a funded balance. That key is a normal VirtualSMS key. It works with every endpoint on this page — verifications, rentals, proxies and Cloud Browser — at ordinary catalogue prices. Payment in USDC or USDT on Base, BNB Chain or Solana. Minimum top-up $2.50. Full x402 top-up flow, including per-chain requirements →

Usage

Pass your key via header (recommended):

curl https://virtualsms.io/api/v1/balance \
  -H "x-api-key: YOUR_API_KEY"

Or via query parameter:

curl "https://virtualsms.io/api/v1/balance?api_key=YOUR_API_KEY"

Never expose your API key in client-side code or public repositories.

Errors

Status	Meaning
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Key valid but insufficient permissions
`429 Too Many Requests`	Rate limit exceeded

Getting Started

Integration

Earn

Get your API key

Create keys programmatically

Usage

Errors

​Get your API key

​Create keys programmatically

​Agents: get an API key without a signup flow

​Usage

​Errors

Get your API key

Create keys programmatically

Agents: get an API key without a signup flow

Usage

Errors