Overview

OpenXSwitch uses a role-based API permission system to control access to various functionalities within a workspace. Each API key must have the appropriate permissions assigned to access specific endpoints.

🔑 API keys are environment-specific, sandbox keys work only in the sandbox, while a new live key is required for production.

Permission Levels

Permissions are categorized based on the level of access granted:

Permission	Description
`read`	Grants access to view data without modifying records. Used for retrieving balances, transaction history, and market data.
`write`	Required for any action that modifies records or changes the state of the system. Examples include updating settings, creating sub-accounts, or initiating transactions.
`withdraw`	Required to initiate fund withdrawals from a wallet. This permission must be combined with `write`.
`sub-wallet`	Allows management of sub-wallets, including creation, retrieval, and transfers.
`transfer`	Enables internal transfers between wallets or sub-accounts. Requires `write` permission.
`swap`	Grants access to asset swapping functionality within the platform. Requires `write` permission.
`trade`	Enables trading actions such as `instant swap` placing `market` or `limit` orders. Requires `write` permission.
`ramp`	Allows usage of fiat on/off-ramp services for converting between crypto and fiat. Requires `write` permission.

Permission Dependencies

Some actions require multiple permissions to be granted together:

Withdrawals (withdraw) → Requires write+withdraw
Transfers (transfer) → Requires write+transfer
Trading (trade) → Requires write+trade
Swapping (swap) → Requires write+swap
Ramp (ramp) → Requires write+ramp

Checking Permissions Before an Action

Before executing an API request, the system checks for the required permissions. Example response when permission is missing:

{
  "statusCode": 403,
  "timestamp": "....",
  "path": "/v1/withdraw",
  "message": "The API key does not have 'withdraw' permission."
}

Security Considerations

API keys with write, withdraw, transfer, or trade permissions should be stored securely.
Use role-based access control to limit permissions based on user roles.
Enable IP whitelisting and other security features to protect API access.