Authentication
Every request carries an API key as a Bearer token. Keys have permissions and can be limited to some of your MetaTrader accounts and to a time.
Updated
Bearer keys
Send the key in the Authorization header, exactly as Bearer <key> (capital B, one space). Keys look like gw_<12 hex characters>_<secret>; the first part (the prefix) identifies the key in lists and logs, the secret is stored only as a hash.
curl https://api.propmetaapi.com/v1/accounts \
-H "Authorization: Bearer gw_1a2b3c4d5e6f_Xy9…"- A missing, malformed, wrong, revoked or expired key answers 401 UNAUTHORIZED. A revoked key stops within seconds and its open WebSockets close within 10 seconds (close code 4401).
- Too many failed authentications from one address (30 in a minute) block that address for the rest of the minute with 429 RATE_LIMITED — fix the key instead of retrying.
- If your access has an IP allowlist, other addresses get 403 FORBIDDEN_IP.
GET /v1/debug/headersshows the address the gateway sees. - The WebSocket accepts the key in the same header, or as a sub-protocol for browsers — see WebSocket streaming.
Your primary key
The key issued with your plan has every permission (read, trade, manage) on all your accounts. In Account → API → Token & keys you can:
- Reveal — show and copy it after confirming your password (and 2FA code, if enabled).
- Rotate — issue a new primary key; the old one stops working within seconds. Keys you made yourself with POST /v1/keys stay valid.
Another key cannot revoke the primary key through the API (403 FORBIDDEN); rotate it in the panel. A renewal of your plan keeps your keys.
Permissions
A key has one or more permissions. A call the key is not allowed to make answers 403 FORBIDDEN and names the permission it needs:
| Permission | Allows |
|---|---|
read | Every GET (accounts, positions, orders, history, quotes, symbols, statistics, events, commands …), the WebSocket /v1/ws, and the POST / DELETE calls that only read or follow data: POST …/check, POST and DELETE …/subscriptions, POST …/rates/requests, POST and DELETE …/tick-history, POST …/refresh, POST /v1/tools/ping-host. |
trade | Trade commands: POST …/orders, PATCH and DELETE …/orders/{orderId}, PATCH …/positions/{positionId}, POST …/close and …/close-by, POST …/close-all, PUT and DELETE trailing stops. |
manage | Every other change: register, activate, deactivate, reconnect and remove accounts, passwords and proxy, watches, broker files, risk trackers, webhooks, keys, copy trading. Reading keys, webhooks, invoices and usage needs manage too. |
403 Forbidden
{
"code": "FORBIDDEN",
"message": "this API key has no \"trade\" permission",
"retryable": false,
"details": { "permission": "trade", "keyPermissions": ["read"] }
}- Risk trackers whose action closes positions (CLOSE_POSITIONS, CLOSE_AND_BLOCK) and copy-trading settings make trades: they need trade as well as manage.
- Client-wide calls need a key that is not limited to some accounts: registering accounts, uploading / replacing / removing broker files, invoices and usage, copy trading.
- The API reference names the permission of every endpoint.
Scoped keys
Create narrower keys for each app, server or teammate with POST /v1/keys (needs manage) or in the panel (it asks for your password and, with 2FA on, your code). The full key is in the answer once — store it right away.
curl -X POST https://api.propmetaapi.com/v1/keys \
-H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "reporting dashboard",
"permissions": ["read"],
"accountIds": ["3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10"],
"expiresAt": "2026-12-31T23:59:59Z"
}'{
"id": "b7e1…",
"prefix": "9f8e7d6c5b4a",
"label": "reporting dashboard",
"scope": "CLIENT",
"permissions": ["read"],
"accountIds": ["3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10"],
"issuedBy": "client",
"createdAt": "2026-10-05T09:00:00.000Z",
"expiresAt": "2026-12-31T23:59:59.000Z",
"revokedAt": null,
"lastUsedAt": null,
"key": "gw_9f8e7d6c5b4a_…" ← shown only in this answer
}const res = await fetch("https://api.propmetaapi.com/v1/keys", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.GW_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ label: "copier", permissions: ["read", "trade"], accountIds: [accountId] }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const created = (await res.json()) as { id: string; key: string };
console.log(created.key); // shown once — store it nowpermissionsmust be a subset of the calling key's (default: the same). A key limited to some accounts can only make keys for a subset of them.accountIdslimits the key to those accounts: every other account answers 404, the event feed, WebSocket and webhooks only show theirs (plus events without an account, such as plan notices).expiresAtends the key at that time; a key never outlives the key that made it. Revoking a key also revokes the keys it made.- You can hold up to 20 working keys of your own (403 QUOTA_EXCEEDED beyond that — revoke one first).
# keys this key may manage (current: true marks the calling key)
curl https://api.propmetaapi.com/v1/keys -H "Authorization: Bearer $GW_KEY"
# revoke a key (and every key it made); its WebSockets close within 10 s
curl -X DELETE https://api.propmetaapi.com/v1/keys/$KEY_ID -H "Authorization: Bearer $GW_KEY"Rotating a scoped key without downtime: create the new key, deploy it, then revoke the old one.
Rate limits
Requests are counted per customer and calendar minute in two separate buckets: trade calls (tradesPerMin) and all other calls (requestsPerMin). All your keys share the same buckets, so a second key does not double the limit. Your limits are limits.requestsPerMin and limits.tradesPerMin in GET /v1/me. Over the limit the answer is 429 RATE_LIMITED with a Retry-After header (seconds until the next minute).