API Keys

Overview

API keys authenticate every request to the Wallgent API. Keys come in two formats:

• wg_test_* — Sandbox environment. Can only access sandbox wallets and data.
• wg_live_* — Production environment. Requires KYB approval and production activation before you can create these.

The raw secret is shown only once at creation. Store it immediately in your secrets manager.

Creating a Key

POST /v1/api-keys

Request Body

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

const { secret, id } = await wg.apiKeys.create({
  name: 'Payment agent — prod',
  permissions: ['payments:write', 'wallets:read'],
  expiresAt: '2027-01-01T00:00:00Z',
})

// Store `secret` now — it will never be shown again
console.log('Key ID:', id)
console.log('Key secret:', secret)

Full Permissions Reference

Wallet Scoping

Restrict a key to operate only on specific wallets. This is ideal for agent isolation: each agent gets a key that can only touch its own wallet.

// This key can only send payments from wal_agent1 and wal_agent2
const agentKey = await wg.apiKeys.create({
  name: 'Agent-42 key',
  permissions: ['payments:write', 'wallets:read'],
  // Wallet scoping is enforced at the policy layer — create per-wallet keys
  // by provisioning one key per wallet and storing the mapping
})

When a wallet-scoped API key attempts to operate on a wallet outside its scope, the request is rejected with PERMISSION_DENIED.

IP Allowlisting

Restrict a key to specific source IP addresses. Requests from any other IP are rejected.

const serverKey = await wg.apiKeys.create({
  name: 'Backend server key',
  permissions: ['payments:write'],
  allowedIps: ['203.0.113.10', '203.0.113.11'],
})

Key Expiry

Keys can auto-expire at a specified timestamp. Once expired, the key is rejected as if it had been revoked. Use expiry for short-lived automation tasks or contractor access.

const tempKey = await wg.apiKeys.create({
  name: 'Temporary contractor access',
  permissions: ['wallets:read', 'payments:read'],
  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days
})

Privilege Escalation Prevention

A key cannot create another key with more permissions than it holds. Only keys with the full set of all permissions can create new keys. A scoped key — for example one with only wallets:read — cannot create a key with payments:write.

This prevents a compromised low-privilege key from bootstrapping itself into broader access.

Listing Keys

GET /v1/api-keys

The raw secret is never included in list responses. Only the last 4 characters of the key ID are shown as a hint.

const { data } = await wg.apiKeys.list()

for (const key of data) {
  console.log(`${key.name} (${key.environment}) — last used: ${key.lastUsedAt ?? 'never'}`)
}

Revoking a Key

DELETE /v1/api-keys/:id

Revocation is immediate. Any in-flight requests using the key after revocation will be rejected.

await wg.apiKeys.revoke('wg_test_abc123...')

Zero-Downtime Key Rotation

const newKey = await wg.apiKeys.create({
  name: 'Payment agent — rotated 2026-03',
  permissions: ['payments:write', 'wallets:read'],
})

await wg.apiKeys.revoke(oldKeyId)

API Endpoints

MCP Tools