Skip to main content

API Reference

The Shroud API is organized around REST. Requests and responses use JSON, and authentication is performed with a Bearer token in the Authorization header.

Base URL

https://api.shroud.dev/v1

Profiles​

A Profile is the top-level managed identity container. It can include a card, phone number, and inbox.

Create a Profile​

POST /v1/profiles
{
  "budget": 50.0,
  "capabilities": ["card", "phone", "email"],
  "merchant_lock": "amazon.com"
}

Parameters​

ParameterTypeRequiredDescription
budgetnumberYesMaximum spend limit in USD
capabilitiesstring[]YesAny combination of card, phone, and email
merchant_lockstringNoRestrict the card to a specific merchant
ttl_secondsintegerNoAuto-destroy after the specified number of seconds

Response​

{
  "id": "prf_92x71a",
  "status": "active",
  "card": {
    "id": "crd_8x2k",
    "number": "4242424242421234",
    "cvv": "847",
    "exp_month": 12,
    "exp_year": 2027,
    "budget_remaining": 50.0
  },
  "phone": {
    "id": "phn_3j9f",
    "digits": "+14155550192",
    "carrier": "t-mobile"
  },
  "email": {
    "id": "eml_7k1p",
    "address": "agent_8x2k@proxy.shroud.dev"
  },
  "created_at": "2026-03-16T11:00:00Z",
  "expires_at": "2026-03-16T12:00:00Z"
}

Destroy a Profile​

DELETE /v1/profiles/:id

Immediately destroys all credentials linked to the profile.

List Profiles​

GET /v1/profiles?status=active&limit=20

Virtual Cards​

Cards are usually created with a profile, but they can also be managed directly.

Get Card Details​

GET /v1/cards/:id

Update Card Budget​

PATCH /v1/cards/:id
{
  "budget": 100.0
}

Pause or Resume Card​

POST /v1/cards/:id/pause
POST /v1/cards/:id/resume

Phone Numbers​

Real-SIM backed phone numbers are designed for receiving OTPs in production-like sign-up flows.

Provision a Phone​

POST /v1/phones
{
  "country_code": "US",
  "carrier_preference": "tier-1"
}

Wait for SMS​

GET /v1/phones/:id/sms?timeout=30
{
  "id": "sms_9f2a",
  "from": "+18005551234",
  "body": "Your verification code is 849102",
  "extracted_otp": "849102",
  "received_at": "2026-03-16T11:02:30Z"
}

Email Inboxes​

Temporary inboxes can extract OTPs and verification links from raw email content.

Generate an Email​

POST /v1/emails
{
  "domain": "proxy.shroud.dev",
  "prefix": "agent"
}
GET /v1/emails/:id/extract?timeout=30
{
  "type": "magic_link",
  "url": "https://service.com/verify?token=abc123",
  "subject": "Verify your email address",
  "received_at": "2026-03-16T11:03:00Z"
}