API key lifecycle
Delegate one account’s read or trading capability without delegating custody.
Choose scoped access
Use the owner-approved connection flow for an independent trading client or agent. The owner approves one account, the requested scopes and a limited lifetime. Begin with read access while validating the integration, then request trade access when the owner is ready to enable commands.
Agent keys default to 24 hours. A grant may request a lifetime from five minutes to seven days. Check the issued key’s metadata for its actual account, scopes, state and expiry.
| Scope | Permitted use | Owner control |
|---|---|---|
| read | Account reads, order previews and realtime tickets | Owner approves the account and lifetime |
| trade | Read access plus order placement and cancellation | Owner explicitly approves trading capability |
Read scope and trade scope
A read key can inspect the approved account, its positions, orders and fills, request an order preview, check readiness, and mint a realtime ticket. A trade key includes read access and adds single or batch order placement and cancellation. Public market data needs neither.
A read key attempting an order receives 403 scope_insufficient. Deposits, withdrawals, secure identity changes, approving other agents and listing or revoking keys remain behind the owner's session and return 403 passkey_required to keys. Transfers, private affiliate data and favorites editing are also outside the published key allowlist. Do not interpret a new authenticated endpoint as automatically accessible to keys.
Inspect and store a key securely
GET /v1/api-keys/current returns the current key's account, principal kind, scopes, display prefix, state and timestamps. It never returns the secret and rejects owner sessions; it is specifically a key-inspection route. Check active state, approved account, scopes and expiresAtEpochMs before enabling a strategy.
Store the key in a private secret store or a file readable only by its intended user. Load it inside the client process. Avoid shell arguments, committed configuration, chat transcripts, debugging output and request-header logs. Redact both Authorization and realtime ticket fields from telemetry.
import { readFile } from 'node:fs/promises';
// Set this environment variable to a private credential file path.
const keyFile = process.env.EDEL_API_KEY_FILE;
if (!keyFile) throw new Error('EDEL_API_KEY_FILE is required');
const apiUrl = process.env.EDEL_API_URL;
if (!apiUrl) throw new Error('EDEL_API_URL is required');
const apiKey = (await readFile(keyFile, 'utf8')).trim();
const response = await fetch(
new URL('/v1/api-keys/current', apiUrl),
{ headers: { Authorization: `Bearer ${apiKey}` } },
);
if (!response.ok) throw new Error(`Metadata request failed: ${response.status}`);
const metadata = await response.json();
console.log({
state: metadata.state,
principalKind: metadata.principalKind,
scopes: metadata.scopes,
expiresAtEpochMs: metadata.expiresAtEpochMs,
});Renew and revoke through the correct path
Agent keys cannot renew themselves. Start a new device grant and obtain owner approval for a fresh key before the current grant expires. Store the replacement securely and recheck its account, scopes and expiry.
The owner can revoke a key with their browser session. Expiry and revocation are checked on requests. A key cannot list or revoke another key, and a program cannot approve its own replacement. Treat revocation as a stop signal, not an invitation to repeatedly request access.
Handle API-key errors
These are API-key refusals, distinct from ordinary order validation or rate limiting. Preserve the requestId when escalating an issue, without attaching the key.
| HTTP / apiKeyRejection | Client action |
|---|---|
| 401 malformed / unknown / expired | Correct credential loading or repeat the appropriate issuance flow |
| 401 revoked | Stop and obtain owner direction |
| 401 principal_unavailable | Stop and contact the venue |
| 403 scope_insufficient | Request owner approval for the needed scope |
| 403 passkey_required | Return the action to the owner in the browser |
| 403 environment_forbidden / principal_mismatch | Correct the key kind, environment or route |
| 503 store_unavailable | Retry later with the same request and mutation identity |
Check route-specific permissions
Each private operation has a credential policy in addition to its account and scope checks. Check that the route accepts an API key before integrating it; bearer authentication alone does not mean that a trading key is permitted.
Use the current-key endpoint to verify a key’s account, scopes and expiry. Key listing, revocation and agent approval require an owner session. See authentication failures for rejection handling and agent access for the owner-approved connection flow.