Docs/Authentication

Authentication

Secure your API requests using API keys. Every request must include a valid API key in the header.

API Key Types

Web3 Pay uses API keys to authenticate requests. You can manage your keys in the Dashboard.

Key Type	Prefix	Usage
Secret Key (Live)	wp3_live_sk_	Server-side requests in production
Secret Key (Test)	wp3_test_sk_	Server-side requests in test mode
Publishable Key (Live)	wp3_live_pk_	Client-side widget initialization
Publishable Key (Test)	wp3_test_pk_	Client-side widget in test mode

Keep your secret keys safe

Secret keys should never be exposed in client-side code. Only use publishable keys in frontend applications.

1Making Authenticated Requests

Include your API key in the X-API-Key header of every request.

bash

-green-400">curl https://api.web3pay.io/v1/onramp \
  -H "X-API-Key: wp3_live_sk_your_secret_key" \
  -H "Content-Type: application/json"

2SDK Authentication

When using our SDK, pass your API key during initialization:

javascript

400">import { Web3Pay } 400">from 400">&#039;@web3pay/sdk&#039;;

400">const client = 400">new Web3Pay({
  apiKey: 400">&#039;wp3_live_sk_your_secret_key&#039;,
  500">// Optional: custom base URL for self-hosted deployments
  baseUrl: 400">&#039;https:500">//api.web3pay.io&#039;
});

API Key Permissions

API keys can be scoped with specific permissions to limit access. Configure permissions when creating a new key.

Permission	Description
onramp:create	Create new onramp sessions
onramp:read	Read onramp session details
transactions:read	List and view transactions
keys:manage	Create and revoke API keys
webhooks:manage	Configure webhook endpoints

Key Security Best Practices

Store keys securely

Never commit API keys to version control. Use environment variables or a secrets management service.

Rotate keys regularly

Create new keys periodically and revoke old ones. This limits exposure if a key is compromised.

Use minimal permissions

Only grant the permissions each key needs. Create separate keys for different services or environments.

Monitor key usage

Review API logs in your dashboard to detect unusual activity or unauthorized access attempts.

Example: Using Environment Variables

.env

# Never commit this file to git!
WEB3PAY_SECRET_KEY=wp3_live_sk_your_secret_key
WEB3PAY_PUBLISHABLE_KEY=wp3_live_pk_your_publishable_key
WEB3PAY_WEBHOOK_SECRET=whsec_your_webhook_secret

server.js

400">import { Web3Pay } 400">from 400">&#039;@web3pay/sdk&#039;;

400">const client = 400">new Web3Pay({
  apiKey: process.env.WEB3PAY_SECRET_KEY
});

Authentication Errors

When authentication fails, the API returns one of these error codes:

Error Code	HTTP Status	Description
MISSING_API_KEY	401	No API key provided in request
INVALID_API_KEY	401	API key is invalid or has been revoked
INSUFFICIENT_PERMISSIONS	403	Key lacks required permission for this endpoint