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

# Authentication

> Send an arena_sk_ key as a bearer token. Scopes decide what it can do.

## Header

```http theme={null}
Authorization: Bearer arena_sk_…
```

Clients that cannot set `Authorization` may send `x-arena-key: arena_sk_…` instead. HTTPS only.

| Result | When |
| - | - |
| `401 unauthorized` | No credential. Carries `WWW-Authenticate: Bearer` with `error="invalid_request"`. |
| `401 invalid_token` | Key is malformed, unknown, revoked or expired. One answer for all four, on purpose. |
| `403 insufficient_scope` | Valid key without the scope the endpoint checks. Create a new key with it. |

## Scopes

| Scope | Grants |
| - | - |
| `records:read` | Public records: [`GET /leaderboard`](/api-reference/records/get-a-leaderboard), [`/eval`](/api-reference/records/get-the-eval-board), [`/traders/{traderId}`](/api-reference/records/get-a-trader), [`/traders/{traderId}/picks`](/api-reference/records/get-a-traders-settled-picks), [`/traders/{traderId}/track-record`](/api-reference/records/get-a-traders-signed-track-record). |
| `portfolio:read` | The key owner's own account: [`GET /account`](/api-reference/portfolio/get-your-account), [`/portfolio`](/api-reference/portfolio/get-your-portfolio), [`/portfolio/trades`](/api-reference/portfolio/list-your-trades), [`/me/eval`](/api-reference/portfolio/get-your-own-eval-rows), and the owner's own `/traders/{traderId}/picks` with private picks included. `GET /portfolio` and `GET /portfolio/trades` also accept [`X-Arena-Org`](#organization-sandbox). |
| `markets:read` | Instruments, games and a paper replay: [`GET /instruments`](/api-reference/markets/list-instruments), `/instruments/search`, `/instruments/{ref}`, `/games`, `/games/{ref}`, [`POST /backtest`](/api-reference/markets/replay-settled-game-winner-markets-on-paper), and the quotes routes once [venue data](/conventions/privacy-and-venue-data#venue-data) is on. Keys created before this scope existed lack it. |
| `trade:write` | Paper orders: [`POST /portfolio/orders`](/api-reference/trading/place-a-paper-order) and [`DELETE /portfolio/orders/{orderId}`](/api-reference/trading/cancel-a-paper-order). Both accept [`X-Arena-Org`](#organization-sandbox). Never a default scope; request it when creating the key. Refused with `403 scope_not_available` while trading with keys is switched off. |
| `trade:write:kalshi` | Live Kalshi orders: `execution` `kalshi` on `POST /portfolio/orders`, cancel with `execution=kalshi`, and [`POST /portfolio/orders/{orderId}/amend`](/api-reference/trading/amend-a-live-kalshi-order). Needs a trading key in Settings. Off unless you request it. Live submission stays off while `ARENA_KALSHI_LIVE_TRADE` is off. |
| `trade:write:poly-intl` | Live Polymarket International orders: `execution` `poly-intl` on `POST /portfolio/orders`, and cancel with `execution=poly-intl`. Needs credentials in Settings. Off unless you request it. A blocked country is refused (`us_not_eligible`). There is no Polymarket US scope. Live submission stays off while `ARENA_POLY_INTL_LIVE_TRADE` is off. |

[`GET /me`](/api-reference/identity/get-me), [`GET /usage`](/api-reference/usage/get-usage) and [`GET /organizations`](/api-reference/identity/list-your-organizations) accept any valid key. [`GET /status`](/api-reference/status/get-status) needs none.

## Organization sandbox

`GET /portfolio`, `GET /portfolio/trades`, `POST /portfolio/orders` and `DELETE /portfolio/orders/{orderId}` take an optional header:

```http theme={null}
X-Arena-Org: 00000000-0000-4000-8000-000000000000
```

The value is an organization id (at most 63 characters). With the header, the call uses that organization's paper sandbox under the same scope (`portfolio:read` or `trade:write`). `GET /portfolio` returns that sandbox's cash, positions and resting orders, and `organization.slug`. `GET /portfolio/trades` returns that sandbox's trades, not the personal trade list, and `organization.slug` when the sandbox named one. Neither read returns the personal account. Order routes include `organization` (`id`, and `slug` when set). Without the header, the call uses the key owner's personal paper account and `organization` is absent. `GET /account` is the personal account.

[`GET /organizations`](/api-reference/identity/list-your-organizations) lists the organizations this personal key belongs to. Any valid key, no particular scope. Each `id` is the value `X-Arena-Org` takes. The list ignores `X-Arena-Org`. A 2xx body has `mode` `paper`. GET takes no query parameters; every other method answers `405 method_not_allowed`.

| Result | When |
| - | - |
| `400 invalid_request` | The value is not an organization id. |
| `403 organization_forbidden` | The key cannot use that organization. The personal account is not read or traded. |
| `404 organization_not_found` | No organization has that id. The personal account is not the fallback. |

The header does not select a Combine evaluation account. Paper only.

## Sessions

[Key management](/getting-started/api-keys#key-management-endpoints) uses a person's session instead of a key: the website's cookie, or a signed-in CLI's session token as the bearer. There is no guest or anonymous access.

<Note>
  The playground in the API reference sends requests through Mintlify's proxy. Use a key you can revoke, with only the scopes you need.
</Note>


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