API Key permissions (roles)¶
Evidence: ptrader-api-gateway/docs/API-Authentication-Mechanism.en.md, AuthFilter role checks.
A key may carry multiple roles (comma-separated integers).
| Role | Value | Typical use |
|---|---|---|
| READ_ONLY | 0 | Balances, history reads |
| TRADE | 2 | Place / cancel orders (tradeOnly / write trade endpoints) |
| CONVERT | 3 | Convert APIs (convertOnly) |
| CRYPTO_WALLET | 4 | Deposit / withdraw |
| FIAT | 5 | Fiat APIs |
| ACCOUNT | 6 | Account management (accountOnly) |
Endpoint annotation effects (gateway)¶
| Annotation flag | Effect |
|---|---|
needWrite=true |
Rejects read-only-only keys |
tradeOnly=true |
Requires role 2 |
convertOnly=true |
Requires convert role |
accountOnly=true |
Requires account role |
validKeyOnly=true |
Skip HMAC; validate key only |
checkRecvWindow=true |
Enforce timestamp / recvWindow |
Exact role combinations per endpoint: see OpenAPI security + controller @SignAuth in ptrader-api-gateway. [NEEDS-CONFIRMATION: publish a per-endpoint role matrix for integrators]
Creating keys¶
API key creation / secret display is not part of this public OpenAPI surface (create-api-key tool routes are excluded). Use the product UI / approved onboarding channel.