What is API key permissions?
The specific rights attached to an exchange API key, typically read-only, trading, and withdrawal, each of which can usually be granted separately.
Not yet verifiedHow we verify
3 min read
In this entry
The specific rights attached to an exchange API key, typically read-only, trading, and withdrawal, each of which can usually be granted separately.
A key with withdrawal rights is equivalent to the account itself, so the safe default is read-only for portfolio tools and trade-only for bots, with withdrawal disabled entirely. Most exchanges also let a key be restricted to specific internet addresses, which limits what a leaked key is worth.
The permissions screen appears once, at creation, and most people click through it. That single screen decides whether a future breach of a third-party service costs you your trade history or your balance.
How it works
Rights are additive and independent, so a key can read without trading and trade without withdrawing. The three common tiers behave very differently under compromise.
Read grants balances, order history, and deposit addresses. It cannot move anything. Portfolio trackers and tax importers need nothing more.
Trade grants placing and cancelling orders. A stolen trade-only key cannot withdraw, but it can still destroy value by placing bad orders into a thin book, which is a real loss even though nothing leaves the account.
Withdraw grants moving assets out. On most venues this right is only usable in combination with a withdrawal whitelist, and enabling it typically requires an email confirmation and a waiting period.
Address restriction is the other half. Binding a key to the fixed internet address of the server that uses it means a copied secret is unusable from anywhere else. Tools that run on your laptop cannot use this, because home addresses change.
Example
Illustrative table of what a leaked key costs you, by permission set.
| Permissions granted | What an attacker can do | What they cannot do |
|---|---|---|
| Read only | See balances and full trade history | Trade or withdraw |
| Read and trade | Place orders into a thin book at bad prices | Move funds off the venue |
| Read, trade, withdraw, no whitelist | Empty the account | Change your login credentials |
| Read, trade, withdraw, whitelist on | Send only to addresses you already approved | Add a new destination without a delay |
Illustrative; exact behavior and whether whitelisting is mandatory vary by exchange.
Why it matters when you buy
Every tool that connects to your exchange is a copy of your credentials sitting on someone else's server. Granting the minimum turns a third-party breach from a loss into an inconvenience. Review your key list when you change tools, and check what withdrawal controls each venue offers at the exchange directory.
Related terms
- api key — the credential the permissions attach to
- withdrawal whitelist — the restriction that caps withdrawal rights
- sub account — limiting a key to part of the balance
- address book — the saved destinations a whitelist uses
- two factor authentication — required to create or change keys
- counterparty risk — what you take on with every connected tool
Questions
Can I change permissions on an existing key?
Some exchanges allow editing, others require you to delete the key and issue a new one. Where editing is allowed it usually triggers the same email confirmation as creation.
Should I use one key for everything?
No. One key per tool means you can revoke a single compromised service without breaking the others, and it tells you from the audit log which tool did what.
What does address restriction actually protect against?
A leaked secret used from anywhere other than the bound address. It does nothing if the attacker has compromised the server that legitimately holds the key.