API keys - Edel Developer Docs

A person trades in the app with a DFNS passkey session. Programs use scoped API keys. Agent, market-making bot and test-client keys are all checked the same way on every request. They differ in who issues the key, not in the account and route authorization model. Each key is bound to one account. A trade scope includes read.

Principal kind	Who issues it	Approval	Can do	Cannot do	Environments	Expiry
Agent	Agent-connect service after owner approval	Owner reviews the code, account and scopes in the browser with a passkey	Read and trade its one account within scopes	Deposit, withdraw, change Party or manage keys	Local, Development, Staging, Production	24 hours by default, 5 minutes to 7 days as the agent requests
Market-making bot	Venue bot runtime on the server	Workload identity and configured bot-to-account binding, not the browser device grant	Read and trade its one bound account within scopes	Deposit, withdraw, change Party or manage keys	Local, Development, Staging, Production	7 days; bot rotates before expiry
Test client	Test venue service on the server	Test-venue issuance policy, not the browser device grant	Read and trade its one test account within scopes	Deposit, withdraw, change Party or manage keys	Local and Development only	Non-expiring test lifetime; forbidden in Staging and Production

A staging or production venue refuses a test-client key on every request, even if a copy of the key exists there. The published docs do not expose the server-only issuance endpoint. When a key is rotated, the old key keeps working for 5 more minutes, so requests already in flight still land. Then it expires.

When a key is refused

A refused request answers with the external-rest-error/v1 envelope. apiKeyRejection names the reason. Only a 503 is worth a retry; for every other refusal, fix the cause first.

HTTP	`apiKeyRejection`	Meaning	What to do
`401`	`malformed`	The value is not in the Edel key format.	Check how you load and send the key.
`401`	`unknown`	The venue does not recognise the key.	Connect again to get a new key.
`401`	`expired`	The key’s lifetime has ended.	Connect again, or rotate a bot key.
`401`	`revoked`	The owner or the venue revoked the key.	Stop. Ask the owner before you connect again.
`401`	`principal_unavailable`	This venue does not accept this kind of key now.	Stop and contact the venue.
`403`	`scope_insufficient`	The key has `read` but the route needs `trade`.	Ask the owner for a key with the `trade` scope.
`403`	`passkey_required`	The route needs the owner’s passkey session: deposits, withdrawals, Party changes and key management.	Do not retry with a key. The owner does it in the app.
`403`	`environment_forbidden`	This venue does not accept this kind of key.	Use a key kind this venue accepts.
`403`	`principal_mismatch`	This kind of key cannot use this route.	Use the route for your key kind.
`503`	`store_unavailable`	The venue cannot check keys right now.	Retry later with the same key and the same `Idempotency-Key`.

A key is a trading credential, not a signing credential. Protect it as carefully as an order entry credential. An expired or revoked key is refused on every request. The owner can revoke agent access from the app with a passkey. A bot follows its server-side rotation path. A key cannot list or revoke other keys. For agent approval, see Trading agents. For bot integration, see Market maker quickstart. For the shared route and scope rules, see Authentication models.

​When a key is refused

When a key is refused