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

# XentFi Pro Authentication

> Requesting access, getting an API key with the Trade scope, and authenticating requests to XentFi Pro.

XentFi Pro uses the same `apiKey` / `orgId` header pair as the core XentFi API (see [core Authentication](/api-reference/authentication)) — the difference is **access**: your key additionally needs the **Trade** scope, and that scope isn't self-serve today.

## Getting access

<Steps>
  <Step title="Confirm you have a Pro account">
    XentFi Pro trading is gated behind a Pro account, separate from a standard XentFi account.
  </Step>

  <Step title="Request access">
    [Email **support@xentfi.com**](mailto:support@xentfi.com) or complete the [Pro access request form](https://xentfi.com/pro/access). Include your organization ID and the markets/assets you intend to trade.

    <Tip>
      Support responds within **2 hours**.
    </Tip>
  </Step>

  <Step title="Generate a Trade-scoped API key">
    Once access is approved, generate the key from **Settings → API Keys** in the [dashboard](https://dashboard.xentfi.com), same as any other XentFi API key — just select the **Trade** scope when creating it.
  </Step>

  <Step title="Copy your credentials">
    Copy the `apiKey` and your `orgId`. **Store them securely** — the key is shown once.
  </Step>
</Steps>

## Making authenticated requests

Include both headers on every request to `api.pro.xentfi.com`, exactly as you would for the core API:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pro.xentfi.com/v1/orderbook/markets \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id"
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.pro.xentfi.com/v1/orderbook/markets', {
    headers: {
      'apiKey': 'your-api-key',
      'orgId': 'your-org-id'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'apiKey': 'your-api-key',
      'orgId': 'your-org-id',
  }

  response = requests.get('https://api.pro.xentfi.com/v1/orderbook/markets', headers=headers)
  ```
</CodeGroup>

<Warning>
  `api.pro.xentfi.com` is a different host from `api.xentfi.com` — using a Pro-scoped key against the core API host (or vice versa) returns `401 Unauthorized`.
</Warning>

## Scopes & permissions

A Trade-scoped key covers placing, listing, and cancelling your own orders and reading your own trade history and market data. A few endpoints require additional, more privileged permissions not included in a standard Trade key — these are typically reserved for XentFi Pro operators/market makers with an admin relationship, not a general trading integration.

| Permission                  | Grants                                                         | Typical scope |
| --------------------------- | -------------------------------------------------------------- | ------------- |
| `orderbook_order:create`    | `POST /orders`                                                 | Trade         |
| `orderbook_order:read`      | `GET /orders`, `GET /orders/{id}`, fills, wallet trade history | Trade         |
| `orderbook_order:cancel`    | `DELETE /orders/{id}`                                          | Trade         |
| `orderbook_market:read`     | List/get markets, book, trades, ticker, candles, engine status | Trade         |
| `orderbook_market:manage`   | `POST /markets`, `PATCH /markets/{symbol}`                     | Admin         |
| `orderbook_settlement:read` | List/get settlement batches                                    | Trade         |

If a request returns `403 Forbidden` with a message about a missing permission, your key doesn't have that permission attached — this is different from a `401`, which means the key or org ID itself is invalid.

## Authentication response

### Failure (401)

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key or orgId",
    "timestamp": "2026-08-20T12:00:00.000Z",
    "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
  }
}
```

### Missing permission (403)

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing orderbook_market:manage permission",
    "timestamp": "2026-08-20T12:00:00.000Z",
    "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
  }
}
```

This is the same `ErrorResponse` shape used across the rest of the platform — see [Error Handling](/api-reference/errors) for the full error-code reference.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized on api.pro.xentfi.com but the same key works on api.xentfi.com">
    Your key doesn't have the **Trade** scope yet. Request it via [support@xentfi.com](mailto:support@xentfi.com) or the [Pro access form](https://xentfi.com/pro/access) — see [Getting access](#getting-access) above.
  </Accordion>

  <Accordion title="403 Forbidden on POST /markets or PATCH /markets/{symbol}">
    These require `orderbook_market:manage`, an admin-level permission most trading integrations don't need. If you're building market-making tooling rather than an operator/admin tool, use the read/trade endpoints instead — market creation and configuration is typically handled by XentFi Pro operators.
  </Accordion>

  <Accordion title="Order placement returns 409">
    A `409` on `POST /orders` means the matching-engine node handling your request isn't currently the leader for that market's shard — this is a transient condition during failover. Retry the request; a different (or the same) node will pick it up within one lease TTL (\~5s).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/xentfi-pro/quickstart">
    Place your first order.
  </Card>

  <Card title="Order Book concepts" icon="list-ordered" href="/essentials/orderbook">
    Markets, order types, and lifecycle.
  </Card>
</CardGroup>