> For the complete documentation index, see [llms.txt](https://ocx.gitbook.io/ocx-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ocx.gitbook.io/ocx-doc/ocx/authentication/api-keys.md).

# api keys

API keys are the recommended way to authenticate bots and long-running integrations. They're scoped, revocable, and come with a built-in audit trail.

## Key model

Every API key has the following fields:

| Field                       | Description                                                                |
| --------------------------- | -------------------------------------------------------------------------- |
| `id`                        | Public key ID, prefixed `ocx_kid_`. Safe to log.                           |
| `secret`                    | Full secret, prefixed `ocx_sk_`. **Returned exactly once at creation.**    |
| `scope`                     | `read` or `trade` (see below).                                             |
| `allowedIps`                | Optional IP allowlist. Empty = no restriction.                             |
| `expiresAt`                 | Optional expiry timestamp.                                                 |
| `revokedAt`                 | Set when you revoke the key. Revoked keys stop authenticating immediately. |
| `lastUsedAt` / `lastUsedIp` | Best-effort audit fields updated on successful use.                        |
| `name`                      | Your own label, e.g. "delta-neutral bot".                                  |

OCX only ever stores a SHA-256 hash of the secret. The plaintext secret is visible exactly once — on creation — and then destroyed server-side.

## Scopes

| Scope   | Permits                                                                                                                                                              |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`  | All public endpoints; all `GET` endpoints including account reads (balances, positions, trades).                                                                     |
| `trade` | Everything in `read`, plus `POST /perps/orders`, `POST /orders`, `POST /quotes(/bulk)`, `POST /orders/cancel-all`, `POST /wallet/transfer`, `POST /wallet/withdraw`. |

Neither scope allows **managing API keys** — `/perps/me/api-keys*` endpoints require an interactive session (cookie or JWT). An API key cannot mint or revoke another key.

## Creating a key

From the UI: **Portfolio → API Keys → Create Key**.

From the API:

```http
POST /perps/me/api-keys
Authorization: <your session cookie or JWT>
Content-Type: application/json

{
  "name": "delta-neutral bot",
  "scope": "trade",
  "allowedIps": ["203.0.113.10"],
  "expiresInDays": 180
}
```

Response — **store `secret` now**, it will not be shown again:

```json
{
  "id": "ocx_kid_01HW...",
  "secret": "ocx_sk_long_random_string",
  "name": "delta-neutral bot",
  "scope": "trade",
  "allowedIps": ["203.0.113.10"],
  "expiresAt": "2026-10-21T12:00:00Z"
}
```

### Options at creation

* **`allowedIps`** — set to an array of IPv4 addresses to restrict usage. If omitted or empty, the key can be used from any IP.
* **`expiresInDays`** — `0` or omitted means the key never expires. We recommend a 90- or 180-day rotation for trading keys.
* **`name`** — free-text label; helpful if you run multiple keys across environments (e.g., `"staging-backtester"`, `"prod-executor"`).

## Using a key

Include the secret as a Bearer token on every request:

```http
GET /perps/positions
Authorization: Bearer ocx_sk_...
```

```bash
curl -sS https://api.ocx.global/perps/markets \
  -H "Authorization: Bearer ocx_sk_..."

curl -sS https://api.ocx.global/perps/orders \
  -H "Authorization: Bearer ocx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "BTC-PERP",
    "side": "buy",
    "type": "limit",
    "price": "67000",
    "quantity": "0.1",
    "timeInForce": "gtc"
  }'
```

## Listing your keys

```http
GET /perps/me/api-keys
Authorization: <session>
```

```json
{
  "keys": [
    {
      "id": "ocx_kid_01HW...",
      "name": "delta-neutral bot",
      "scope": "trade",
      "allowedIps": ["203.0.113.10"],
      "expiresAt": "2026-10-21T12:00:00Z",
      "createdAt": "2026-04-24T12:00:00Z",
      "revokedAt": null,
      "lastUsedAt": "2026-04-24T12:30:00Z",
      "lastUsedIp": "203.0.113.10",
      "status": "active"
    }
  ]
}
```

`status` is one of `active`, `expired`, or `revoked`.

## Revoking a key

```http
DELETE /perps/me/api-keys/{id}
Authorization: <session>
```

```json
{ "message": "API key revoked" }
```

Revocation is immediate — any in-flight request using the key will complete, but the very next authenticated call will fail with `401`.

## Audit trail

Every creation, use, and revocation is logged with timestamp, IP, and user-agent. If a key is compromised, you can review its activity and identify when the misuse began.

## Security checklist

* **Store secrets in a secrets manager** (Vault, AWS Secrets Manager, 1Password, etc.). Never in version control.
* **Use `read` keys wherever possible** — reserve `trade` for the minimum subset of systems that actually submit orders.
* **Set an IP allowlist** for production keys.
* **Set expiry** for all keys; rotate on a schedule.
* **One key per environment.** Don't share a single key across staging, prod, and local dev — you lose the ability to revoke precisely.
* **Monitor `lastUsedAt`** for keys you believe should be idle.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ocx.gitbook.io/ocx-doc/ocx/authentication/api-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.