Account provisioning and entitlements

Create users, create accounts, and activate required market data access.

Creating a trading account does not automatically activate market data.

After account creation, the user may have PENDING entitlements. Your integration must authorize the entitlements the user should receive.

All account and entitlement requests are evaluated in the active Prop Firm context. Use the same authenticated firm context for the complete flow; a user, challenge, phase, or entitlement configured for another firm is not a valid target.

If you create the account but skip entitlement authorization, the user can remain eligible for market data but not receive active data access, meaning they cannot trade or see live market data. Always include entitlement authorization in your account provisioning flow.

​

Recommended flow

1. Create or confirm the user

   Create the user before creating an account for them.

   POST /api/users/
   

   Store the returned user_id. You will use that value when creating the account and when authorizing the user’s entitlements.

2. Create the trading account

   Create the account against the correct challenge using the user_id from the user creation response. The smallest supported request is:

   POST /api/accounts/
   

   {
     "user_id": 123,
     "challenge_id": 1,
     "is_active": true
   }
   

   Store the returned account_id for later account operations and support lookups. If phase_id is omitted, the account uses the first phase configured for the challenge. An explicit initial_balance overrides the phase balance; otherwise the phase balance falls back to the challenge balance. Account creation may create PENDING entitlements based on the challenge configuration.

3. Inspect required entitlements

   Read the user’s entitlements after account creation using the stored user_id.

   GET /api/entitlements/user-entitlements/{user_id}/
   

   Use this response to find the exact entitlement and level values to send in the payload to authorize the individual entitlement returned by the API.

4. Authorize each required entitlement

   Authorize the exchange entitlement or entitlements the user should receive. You can target one named entitlement or several exchange codes in a single request; provide exactly one selector.

   PATCH /api/users/{user_id}/entitlements/
   

​

Example authorization request

{
  "entitlement": "CBOT",
  "level": "l1",
  "status": "AUTHORIZED"
}

To authorize Level 1 access for multiple exchanges in one request:

{
  "exchange_codes": ["cme", "cbot", "comex", "nymex"],
  "level": "l1",
  "status": "AUTHORIZED"
}

For an L1 request, the user must already be eligible for every listed exchange through the active firm.

A successful authorization returns 204 No Content with no response body.

The entitlement selector identifies one package by name and level. Use exchange_codes when you want to update multiple exchange-backed entitlements together:

{
  "exchange_codes": ["cme", "cbot"],
  "level": "l2",
  "status": "AUTHORIZED"
}

Exchange codes are normalized case-insensitively. Do not send both entitlement and exchange_codes in the same request.

​

Status values

Status	Meaning
PENDING	Eligible, but not active. The user does not receive market data yet.
AUTHORIZED	Active access for the selected market-data entitlement.
REVOKED	Access removed.

An entitlement is a market-data package or exchange access level. The read endpoint can expose both an aggregate status and a firm-specific firm_status. status represents the user’s overall access across eligible sources; firm_status represents the access granted by the active firm. They can differ when another eligible source still grants access.

​

L1 and L2 behavior

• L1 updates require the user to already be eligible for the matching entitlement through the active firm. Account creation normally prepares this access from the challenge’s configured entitlements.
• L2 updates can create missing access for the firm, so they can be used for direct add-on access.
• The same firm will not create duplicate access for the same user and market-data entitlement. Creating another account does not automatically reset previously revoked access to PENDING; explicitly authorize it when access should be restored.

​

Validation and errors

• 400 Bad Request: the payload is invalid, both selectors are supplied, the user is not valid for the active firm, or the account’s challenge/phase cannot be resolved.
• 404 Not Found: the named entitlement or exchange code does not exist, or the user is not already eligible for the requested L1 entitlement through the active firm.
• 204 No Content: the entitlement status was created or updated successfully. There is no JSON response to parse.

​

Integration guidance

• Make entitlement authorization part of your account creation workflow.
• Use one authorization call per named entitlement, or group matching exchange codes in one exchange_codes request.
• Authorization is firm-specific. Each firm manages its own users independently.
• Repeating the same status update is safe; downstream update notifications are emitted only when the status changes.
• You can revoke access later by sending status: "REVOKED".

For endpoint schemas and response details, use the API reference tab.