Skip to main content
Each API key is assigned specific permissions that determine which actions and endpoints can be accessed within a workspace.
API keys are environment-specific.
Sandbox API keys only work within the sandbox/tesnet environment, while separate live API keys are required for production usage.

​
Permission Levels

​
Wallet-as-a-Service Permissions

PermissionDescription
readGrants read-only access to wallets, balances, transactions, and operational data.
writeRequired for creating or modifying resources and operational configurations.
withdrawAllows external withdrawals from wallets. Requires write permission.
transferEnables internal transfers between Prime Wallets and Sub-Wallets. Requires write permission.
swapGrants access to swap functionality across supported assets. Requires write permission.
tradeEnables trading operations including market and limit order execution. Requires write permission.
sub-walletAllows creation and management of Sub-Wallet infrastructure.

​
Smart Account Permissions

PermissionDescription
readGrants read-only access to accounts, wallets, balances, and transaction activity.
writeRequired for creating or modifying smart account resources and configurations.
withdrawAllows external withdrawals and asset transfers from smart wallets. Requires write permission.
executeEnables smart account transaction execution including sponsored transactions, batch execution, and programmable wallet operations. Requires write permission.

​
Permission Dependencies

Certain operations require multiple permissions to be assigned together.
ActionRequired Permissions
Wallet Withdrawalswrite + withdraw
Internal Transferswrite + transfer
Swapswrite + swap
Tradingwrite + trade
Smart Account Executionwrite + execute

​
Permission Validation

Before processing a request, OpenXSwitch validates that the API key has the required permissions for the requested action. Example response when permissions are missing: 
{
  "statusCode": 403,
  "timestamp": "2026-05-20T10:00:00.000Z",
  "path": "/v1/withdraw",
  "message": "The API key does not have 'withdraw' permission."
}

​
API Key Management

API keys can be created and managed through: Accounts → API Management Supported management operations include:
  • Create API keys
  • Assign permissions
  • Rotate credentials
  • Revoke compromised keys
  • Monitor API usage
  • View API activity logs

​
Security Considerations & Best Practices

Security PracticeDescription
Principle of Least PrivilegeOnly assign the minimum permissions required for an application or integration.
Secure StorageStore API keys securely using encrypted secret managers or vault infrastructure.
API Key RotationPeriodically rotate sensitive API credentials.
IP WhitelistingRestrict API access to approved IP addresses where supported.
Audit MonitoringMonitor API activity logs for suspicious or unauthorized access patterns.
Withdrawal RestrictionsLimit access to withdrawal permissions to trusted operational systems only.