Docs/API/API Keys

API Keys

Create and manage API keys programmatically. Keys can be scoped with specific permissions for enhanced security.

POST

/v1/keys

Create a new API key. The full key is only returned once at creation time.

Request Body

namestringrequired

A descriptive name for the key (e.g., 'Production Server')

environmentstringrequired

'live' for production or 'test' for development

permissionsarray

Array of permission scopes. Defaults to all permissions if not specified.

bash

-green-400">curl -X POST https://api.web3pay.io/v1/keys \
  -H "X-API-Key: wp3_live_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "environment": "live",
    "permissions": ["onramp:create", "onramp:read", "transactions:read"]
  }'

json

{
  "success": true,
  "data": {
    "id": "key_abc123xyz",
    "key": "wp3_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "name": "Production API Key",
    "environment": "live",
    "prefix": "wp3_live_sk_a1b2c3d4",
    "permissions": ["onramp:create", "onramp:read", "transactions:read"],
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Important: Save the key value immediately. It will not be shown again. We only store a hash of the key for security.

GET

/v1/keys

List all API keys for your account. Full keys are not returned, only prefixes.

bash

-green-400">curl https://api.web3pay.io/v1/keys \
  -H "X-API-Key: wp3_live_sk_your_api_key"

json

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "key_abc123xyz",
        "name": "Production API Key",
        "environment": "live",
        "prefix": "wp3_live_sk_a1b2c3d4",
        "permissions": ["onramp:create", "onramp:read", "transactions:read"],
        "last_used_at": "2024-01-15T14:30:00Z",
        "created_at": "2024-01-15T12:00:00Z"
      },
      {
        "id": "key_def456abc",
        "name": "Test Key",
        "environment": "test",
        "prefix": "wp3_test_sk_x9y8z7w6",
        "permissions": ["onramp:create", "onramp:read"],
        "last_used_at": "2024-01-14T09:15:00Z",
        "created_at": "2024-01-10T08:00:00Z"
      }
    ]
  }
}

DELETE

/v1/keys/:id

Revoke an API key. This action is immediate and cannot be undone.

bash

-green-400">curl -X DELETE https://api.web3pay.io/v1/keys/key_abc123xyz \
  -H "X-API-Key: wp3_live_sk_your_api_key"

json

{
  "success": true,
  "data": {
    "message": "API key revoked successfully"
  }
}

Warning: Revoking a key will immediately invalidate it. Any applications using this key will receive 401 errors.

Available Permissions

Scope your API keys with granular permissions to follow the principle of least privilege.

Permission	Endpoints	Description
onramp:create	POST /v1/onramp	Create new onramp sessions
onramp:read	GET /v1/onramp	Read session status
transactions:read	GET /v1/transactions	List and view transactions
keys:manage	ALL /v1/keys	Create and revoke API keys
webhooks:manage	ALL /v1/webhooks	Configure webhook endpoints

Best Practices

Use separate keys per environment

Create separate keys for development, staging, and production. Never use live keys in test environments.

Limit permissions

Only grant the permissions each key needs. A frontend widget only needsonramp:create while your backend might need more.

Rotate keys regularly

Create a new key, update your applications, then revoke the old key. This limits exposure if a key is compromised.

Monitor usage

Check last_used_at to identify unused keys. Revoke keys that haven't been used in months.