> ## Documentation Index
> Fetch the complete documentation index at: https://tickblaze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!WARNING]
>
> 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.

```http theme={null}
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:

```http theme={null}
POST /api/accounts/
```

```json theme={null}
{
  "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`.

```http theme={null}
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.

```http theme={null}
PATCH /api/users/{user_id}/entitlements/
```

## Example authorization request

```json theme={null}
{
  "entitlement": "CBOT",
  "level": "l1",
  "status": "AUTHORIZED"
}
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"`.

> [!TIP]
>
> For endpoint schemas and response details, use the API reference tab.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.