API Permissions - OpenXSwitch | Docs

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 tesnet environment, while separate live API keys are required for mainnet usage.

Permission Levels

Permission	Description
`read`	Grants read-only access to accounts, wallets, balances, and transaction activity.
`write`	Required for creating or modifying smart account resources and configurations.
`withdraw`	Allows external withdrawals and asset transfers from smart wallets. Requires `write` permission.

Permission Dependencies

Certain operations require multiple permissions to be assigned together.

Action	Required Permissions
Wallet Withdraw	`write` + `withdraw`
Swaps	`write` + `swap`

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": "/v2/transactions/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 Practice	Description
Principle of Least Privilege	Only assign the minimum permissions required for an application or integration.
Secure Storage	Store API keys securely using encrypted secret managers or vault infrastructure.
API Key Rotation	Periodically rotate sensitive API credentials.
IP Whitelisting	Restrict API access to approved IP addresses where supported.
Audit Monitoring	Monitor API activity logs for suspicious or unauthorized access patterns.
Withdrawal Restrictions	Limit access to withdrawal permissions to trusted operational systems only.