API reference

Authentication & scopes

How API keys work, the four scopes, and the rules for keeping them safe.

Every request carries an API key as a bearer token. A key belongs to your organization, not to the person who created it, so staff turnover never silently breaks a running integration.

Every request

curl https://api.propexecutor.com/v1/accounts \
  -H "Authorization: Bearer pfx_live_YOUR_KEY"

Issuing a key

Keys are created in the admin panel, under Developer, by a signed-in owner or admin. The API cannot create keys — that is deliberate, so one leaked credential cannot mint its own replacement and make revoking it pointless.

The token is shown once

We store a hash, not the key. When you create one, the full token appears in that response and never again. If you lose it, revoke it and issue another — there is no way for us to recover it, including for support.

Scopes

A key does only what you tick. A new key with no scopes authenticates successfully and can do nothing, which is the safe default and a useful state in its own right.

Scope	Grants	Care
`accounts:read`	List and read accounts, trades, positions, rule flags, analytics and the equity curve.	Safe. Start here.
`accounts:write`	Provision accounts, assign and reassign traders, archive accounts, create traders.	Provisioning spends account credits permanently.
`credentials:read`	Read and rotate the executor password for an account.	Hands out working logins. Anyone with that password can trade that account.
`trading:write`	Open and close positions on an account, and force a manual breach.	Acts as the trader. Most firms never need this.

A call without the scope it needs returns 403 with code missing_scope, naming the scope it wanted. That is a 403 and not a 401 on purpose: the credential is fine, the permission is not, and a client that re-authenticates on a 401 would otherwise loop.

403 Forbidden

{
  "error": {
    "code": "missing_scope",
    "message": "this API key does not have the `accounts:write` scope"
  }
}

Key format

pfx_live_…string

49 characters: the pfx_live_ marker plus 40 random characters. The marker is there so secret scanners and pre-commit hooks can spot one in a diff.

prefixstring

The first 17 characters, which the panel lists so you can tell two keys apart. Not a secret, and not enough to reconstruct the key.

Handling keys safely

Server-side only. Never put a key in browser JavaScript, a mobile app or anything else a user can read. Call the API from your backend and pass the results to your own frontend.
One key per system. Separate keys for your dashboard, your onboarding job and your staging environment. Rate limits are per-key, so one runaway script cannot starve the others — and you can revoke the one that leaked without taking everything down.
Least scope. A dashboard that only draws charts needs accounts:read and nothing else.
Rotate by overlap. Issue the new key, deploy it, confirm traffic on it, then revoke the old one. Revocation takes effect immediately, so revoking first means downtime.

Revoking

POST/api-keys/:id/revokescope · panel session

Revoke from the panel, or from your own backend with an admin session. The next request on that key returns 401 with invalid_api_key. Keys are revoked rather than deleted, so a key id in an old webhook delivery or a support thread still resolves.

Authentication errors

Status	Code	Means
`401`	`unauthorized`	No `Authorization` header, or not a bearer token.
`401`	`invalid_api_key`	Unknown, malformed or revoked key. One message for all three, so a caller learns nothing about which keys exist.
`402`	`payment_required`	Your organization has not completed its plan purchase yet. See limits.
`403`	`missing_scope`	Valid key, wrong scope.

PreviousQuickstart NextErrors