API Key Management
Creating and managing API keys for programmatic trading
API keys are the primary mechanism for authenticating programmatic requests to the Diffusal API. Market makers and bot operators use API keys to submit orders, receive WebSocket streams, and query account state without requiring wallet signatures on every request.
The API Key Management page is typically the first stop for new dashboard users setting up a programmatic integration.
Creating an API Key
- Click New API Key in the top right of the API Keys page.
- Enter a descriptive label (e.g.
prod-market-maker,staging-bot). - Select the permissions for this key (see Permissions below).
- Click Create Key.
- Copy the key secret immediately — it is shown only once. Store it securely.
The key is active as soon as it is created. There is no additional confirmation step.
Key Permissions and Scopes
| Permission | Description |
|---|---|
| Read | Query positions, orders, collateral balances, and account state |
| Trade | Submit and cancel orders via managed trading endpoints |
| RFQ | Participate in RFQ auctions as a market maker |
| Withdraw | Initiate collateral withdrawals |
Assign only the permissions your integration requires. A read-only key used for data queries should not have Trade or Withdraw permissions.
Viewing Active Keys
The key list shows all active API keys associated with your wallet. Each entry displays:
- Label — The descriptive name you assigned
- Permissions — The scopes granted to this key
- Created — When the key was created
- Last Used — The timestamp of the most recent authenticated request (updated every few minutes)
- Status — Active or Revoked
The key secret is never displayed after initial creation. If you lose a key secret, revoke the key and create a new one.
Revoking Keys
To revoke a key, click the Revoke button on the key row and confirm. Revocation is immediate — any requests using that key will return a 401 Unauthorized error from that point forward.
Revoke keys when:
- You suspect a key has been compromised
- You no longer need the integration it powers
- You are rotating keys as part of a regular security practice
Security Best Practices
- Never share API key secrets. Do not commit them to source control or include them in client-side code.
- Rotate keys regularly. Create a new key, update your integration, then revoke the old key.
- Use the minimum required permissions. A key used only for reading market data does not need Trade permission.
- Label keys clearly. Use environment and purpose in the label (e.g.
prod-mm-alpha,staging-read-only) to make auditing straightforward. - Revoke unused keys. Old keys that are no longer in use are an unnecessary attack surface.
Using API Keys
Pass the API key as a Bearer token in the Authorization header of each request:
Authorization: Bearer <your-api-key-secret>For setup instructions and a working example, see Quick Start. For detailed authentication documentation, see Authentication.