Authentication & Authorization

API Keys

All API requests are authenticated with Bearer tokens:

Authorization: Bearer wg_test_your_key_here

Key Prefixes

Keys are hashed with SHA-256 before storage. The raw key is only shown once at creation time.

Key Properties

Permissions

Every API key must have explicit permissions. Keys without permissions are denied access.

Permission Checks

The API returns 403 with PERMISSION_DENIED when a key lacks the required permission:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Missing required permission: payments:write"
  }
}

Wallet Scoping

API keys can be scoped to specific wallets using the walletScope property. A scoped key can only access the listed wallets — requests to other wallets return 403.

const key = await wg.apiKeys.create({
  name: 'Agent-specific key',
  permissions: ['wallets:read', 'payments:write'],
  walletScope: ['wal_01J_agent_1', 'wal_01J_agent_2'],
});

IP Allowlists

Restrict API key usage to specific IP addresses or CIDR ranges.

const key = await wg.apiKeys.create({
  name: 'Office-only key',
  permissions: ['wallets:read'],
  allowedIps: ['203.0.113.0/24', '198.51.100.42'],
});

Requests from non-allowed IPs return:

{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP not in allowlist"
  }
}

Environment Isolation

Sandbox and production environments are fully isolated:

• Sandbox keys (wg_test_*) can only access sandbox wallets
• Production keys (wg_live_*) can only access production wallets
• Cross-environment access returns 403 ENVIRONMENT_MISMATCH
• Production keys require completed activation (KYB + ToS + billing)

Rate Limits

Rate limits are enforced per API key per minute, based on your plan:

When rate limited, the API returns 429 with a Retry-After header:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 45 seconds."
  }
}

Read operations: GET requests. Write operations: POST, PUT, PATCH, DELETE requests.

Idempotency Keys

For payment and funding operations, include an idempotencyKey to prevent duplicate transactions. Keys are valid for 24 hours.

const payment = await wg.payments.send({
  fromWalletId: 'wal_source',
  toWalletId: 'wal_dest',
  amount: '100.00',
  idempotencyKey: 'pay_order_12345',
});

Duplicate requests with the same key return the cached response. If the same key is reused with different parameters, the API returns 409 IDEMPOTENCY_KEY_REUSE.

Key Lifecycle

Error Reference