Skip to main content

​
Introduction

API keys allow you to interact with the Universal Wallet platform programmatically, enabling automation and integration with your existing systems. This tutorial will guide you through creating your first API key and making your first API request.
API keys provide direct access to your distributor account. Keep them secure and never share them publicly or commit them to version control.

​
Prerequisites

Before you begin, ensure you have:
  • An active distributor account
  • The maker role for creating API keys
  • The checker role for approving API keys (can be a different user)

​
Step 1: Create an API Key (Maker)

1

Navigate to API Keys

Log in to your distributor account and navigate to Settings → API Keys.
2

Click 'New API Key'

Click the New API Key button to start creating a new key.
3

Configure Permissions

Fill in the API key details:Label: Give your key a descriptive name (e.g., “POS Integration”, “Balance Monitor”)Permissions:
  • ✅ Read Balance: Query your distributor wallet balance
  • ✅ Read Transactions: Access operation history
  • ⬜ Perform Operations: Create cash-in/cash-out operations
Only enable “Perform Operations” if you’re building a trusted integration. This permission allows creating financial transactions.
4

Set Limits (Optional)

Configure optional security limits:
  • Max Transaction Amount: Maximum amount per operation (e.g., 100,000)
  • Max Daily Volume: Total daily transaction limit (e.g., 1,000,000)
  • Allowed IPs: Comma-separated list of IP addresses (e.g., 192.168.1.100,10.0.0.5)
  • Expires In: Number of days until the key expires (default: 365)
Setting stricter limits reduces risk if the key is compromised.
5

Submit for Approval

Click Create API Key. The key will be created and sent for approval by a checker.
Due to the maker-checker pattern, you cannot approve your own API key request.

​
Step 2: Approve the API Key (Checker)

1

Navigate to Pending API Keys

Have a user with the checker role log in and navigate to Settings → API Keys → Pending tab.
2

Review the Request

Review the API key request details:
  • Label and permissions
  • Transaction limits
  • IP restrictions
  • Expiration period
3

Approve or Reject

Click Approve to activate the key, or Reject if the request should not be approved.

​
Step 3: Save Your API Key

Important: The API key is displayed only once after approval. You must copy and save it securely.
Once approved, the maker will see a modal displaying the API key: 
uwk_DlbWVU3Vjd11Le43kka6enGNjyd6xtbrBkNHMngl2aNz2Cm7
Copy this key and store it securely. You’ll need it for all API requests.

​
Step 4: Test Your API Key

Let’s make your first API request to verify the key works.

​
Get Distributor Balance

curl -X GET "https://api.yourdomain.com/api/v1/distributors/{distributorID}/balance" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

​
Expected Response

{
  "balance": "50000.00"
}

​
Managing API Keys

​
View Active Keys

Navigate to Settings → API Keys → Active to see all active keys, including:
  • Label
  • Permissions
  • Usage statistics
  • Last used timestamp
  • Expiration date

​
Revoke an API Key

If a key is compromised or no longer needed:
1

Create Revocation Request (Maker)

Click the Revoke button next to the key and provide a reason.
2

Approve Revocation (Checker)

A checker must approve the revocation request in the Pending Revocations tab.
Revoked keys cannot be reactivated. Create a new key if needed.

​
Best Practices

Always use clear, descriptive labels that indicate the purpose and location of the key usage (e.g., “Production POS - Main Store”, “Staging - Balance Monitor”).
Only grant the minimum permissions required. If you only need to check balances, don’t enable “Perform Operations”.
Always configure transaction and daily volume limits to minimize potential damage if a key is compromised.
If your integration runs from fixed IP addresses, restrict the key to those IPs only.
Set appropriate expiration periods and create new keys before old ones expire. Consider rotating keys every 90-180 days.
  • Never hard-code keys in your application
  • Use environment variables or secure secret management systems
  • Never commit keys to version control
  • Restrict access to production keys
Regularly review API key usage in the dashboard. Investigate any unexpected patterns or usage from unknown IPs.

​
Troubleshooting

​
401 Unauthorized

  • Verify the API key is correct and hasn’t been revoked
  • Ensure you’re using the Bearer prefix in the Authorization header
  • Check that the key hasn’t expired

​
403 Forbidden

  • Confirm the key has the required permission for the endpoint
  • Verify the distributor ID in the URL matches the distributor ID associated with the key
  • If using IP whitelisting, ensure your request originates from an allowed IP

​
400 Bad Request

  • Check that you’re using the correct endpoint URL
  • Verify request payload format matches the API specification
  • Ensure required parameters are included

​
Next Steps

Cash-In via API

Learn how to create cash-in operations programmatically

Cash-Out via API

Learn how to process cash-out operations via API

API Reference

Full API endpoint documentation

Security Best Practices

Learn about securing your integration