Guide to API Key Permissions
Overview
Scoped access enables you to set permissions for your production Mesh API keys. Rather than granting unrestricted access, you can define whether each key has Read-only or Read & Write permissions. By managing access to specific API endpoints, you can reduce security risks by ensuring users only have access to necessary resources and nothing more. This is inline with the principles of zero trust and least privilege.
Scope of current implementation
- Permissions are set at the client API key level.
- Permissions can only be set for production API keys, not sandbox keys.
- Permissions cannot be set at the broker-level (ie. clients cannot configure different permissions for Binance vs. Coinbase for the same API key).
- All keys allow for Read access.
- Clients can assign a key Read-only permissions or Read & Write permissions.
- Permissions can only be assigned at the time of key creation, not afterwards. API keys cannot be edited after they’ve been created. Only deleted.
- Read permission enables you to receive successful responses to all read calls to the Mesh API when using this key (eg. Get holdings, Get transfer history, etc.). A production API key always has read access. Even for write functionality, Mesh must read account data like balances as part of transfer configuration.
- Write permission enables you to receive successful responses to all write calls (eg. Execute order, Execute transfer, etc.) to the Mesh API when using this key. If Write permission is not enabled, a call to write data to a linked user account will return a
403error from the Mesh API.
- When connecting their account, users will see a permissions screen that reflects the permissions granted to the API key, as shown below (Read & Write on the left, Read-only on the right).
- When connecting to Coinbase via OAuth, the Mesh API key permissions have been mapped to the OAuth permissions. Therefore, the permissions shown to the user in Coinbase's Oauth window will also reflect there properly.
- However, Mesh API key permissions are not currently mapped to other broker integrations beyond Coinbase. For example, if a Read-only Mesh API key is used to link a user’s Binance account to a client app, that Binance authentication still provides both Read & Write capabilities.
- Rest assured, even though the Binance connection to the client-app does support both Read & Write permissions, any calls to the Mesh API will respect the Mesh API key permissions (in this example, a trade or transfer call to the linked Binance account would return a
403response from the Mesh API). - This mapping is also not yet in place for other OAuth integrations beyond Coinbase. To discuss this further, please email [email protected].
- Rest assured, even though the Binance connection to the client-app does support both Read & Write permissions, any calls to the Mesh API will respect the Mesh API key permissions (in this example, a trade or transfer call to the linked Binance account would return a
How to view & configure API key access scopes
- You can create Mesh API keys by going to Accounts —> API keys.
- When creating a new production API key, you will have the option to enable permissions as shown below.
- We strongly recommend naming keys in a meaningful and logical way. For example, you can use the format:
<company name>-<scope>-<company feature/product>(eg. Mesh-ReadOnly-MeshAggregate) - After a key exists, you can view whether it has Read or Read & Write permissions as shown below.
Updated 23 days ago