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

# Authentication

> Create a key, send it in the Authorization header, and choose the right scopes.

Most API endpoints require an active Pro or Max subscription and a Bearer credential. Send a live API key or an OAuth access token in the `Authorization` header:

```bash theme={null}
curl "https://api.0xinsider.com/api/v1/usage" \
  -H "Authorization: Bearer $OXINSIDER_API_KEY"
```

<span id="create-a-key" />

## Get your first key

<Steps>
  <Step title="Subscribe to Pro or Max">
    Choose a plan on [Pricing](https://0xinsider.com/pricing).
  </Step>

  <Step title="Create a key">
    Open [Developers](https://0xinsider.com/developers) and click **Create key**. Copy the full key; it is shown once.
  </Step>

  <Step title="Save it on your server">
    Read the key from your environment or a secret manager. Use the environment variable `OXINSIDER_API_KEY` with the official clients.

    ```bash theme={null}
    export OXINSIDER_API_KEY="oxi_sk_live_..."
    ```
  </Step>
</Steps>

The Developers page later shows only the prefix and the first 4 hex characters. If you lose the full key, create a replacement and revoke the lost key.

You can build against the [sandbox](/sandbox) before subscribing. It requires no credential and returns sample data.

<span id="the-three-credentials" />

## Choose a credential

| Credential | Use it for | Lifetime and scopes |
| - | - | - |
| Default API key | Your own backend, job, or bot. | It works until revoked and carries all scopes. |
| Named integration key | An integration that needs its own expiry and permissions. | Choose 1 to 90 days and the scopes it needs. Rotation creates a new 90-day key. |
| OAuth access token | An application acting for another user. | It lasts 1 hour and carries the scopes the user granted. |

Live API keys start with `oxi_sk_live_`, followed by 64 hex characters, for 76 characters total. OAuth access tokens start with `oxi_at_`, followed by 64 hex characters; their `oxi_rt_` refresh tokens last 30 days.

An account can have multiple active default keys and up to 10 named integrations. Creating a default key keeps your existing keys valid. During rotation, an integration can temporarily have 2 live keys; the server stores key hashes, rather than the original secrets.

OAuth supports authorization code with PKCE and device authorization for a headless agent or CLI. Follow the [OAuth instructions](https://0xinsider.com/auth.md) to build either flow.

## Set scopes

Default keys carry all 4 scopes. Integration keys and OAuth tokens must include the scope required by the endpoint:

| Endpoint | Required scope |
| - | - |
| `GET /api/v1/usage` | `usage`. |
| Every endpoint under `/api/v1/webhooks` | `webhooks`. |
| Trader exports and whale datasets: submission, status, download, and cancellation | `export`. |
| Other authenticated endpoints, including `/api/v1/me` | `read`. |

A missing scope returns `403 insufficient_scope`. The `WWW-Authenticate` header names the scope you need.

<span id="where-the-key-belongs" />

## Keep credentials private

| Application | Where the credential belongs |
| - | - |
| Backend, scheduled job, or bot | In the server environment or a secret manager. |
| Browser or mobile app | On your own server, which calls 0xinsider for the app. |
| App acting for several users | In each user's OAuth grant, with the scopes they authorized. |
| Headless agent or CLI on another user's machine | In that user's OAuth device authorization flow. |

<Warning>
  Never put a live key in a public browser bundle, mobile binary, repository, Dockerfile, or command-line argument. Anyone who copies it can use its permissions.
</Warning>

Give each integration only the scopes it needs. For an MCP client, use its environment configuration or a secret store rather than including the secret in its arguments.

Keys in URLs are also refused. On an authenticated endpoint, `?token=` returns `401 invalid_api_key` with `error.reason` set to `api_key_in_query`; move it to the Bearer header.

<span id="what-needs-a-key" />

## Endpoints that need no credential

| Endpoint or operation | Access |
| - | - |
| `GET /api/v1` | API discovery. |
| `GET /api/v1/openapi.json` | OpenAPI specification. |
| `GET /api/v1/coverage`, plus its deprecated `/platforms` alias | Feature coverage. |
| `GET /api/v1/health` | API health. |
| `GET /api/v1/pick-of-the-day/ledger` | The public pick ledger. |
| `POST /api/v1/agents/register` | Optional sandbox-key registration. |
| Remote MCP `initialize`, `ping`, and `tools/list` | Connection setup and tool discovery. |
| Sandbox operations | Sample data, with or without an `oxi_sk_test_` key. |

Public API endpoints ignore a supplied credential and a `?token=` parameter. Other data endpoints, Remote MCP `tools/call`, and the live event stream require a valid credential and active Pro or Max access.

<span id="rotate-a-key" />

## Manage your live API keys

Click **Create key** on [Developers](https://0xinsider.com/developers) to add a key. Each key stays valid until you revoke it. Click **Revoke** beside a key to stop only that key; your other keys keep working.

These account-management endpoints require a signed-in Pro or Max website session. A developer API key does not authenticate them.

| Action | Request |
| - | - |
| Create an independent key | `POST /api/keys` with no request body. |
| List key IDs and prefixes | `GET /api/keys`. |
| Revoke one key | `DELETE /api/keys/{id}`. |

To replace a key, create a new one, update every consumer that uses the old key, and revoke the old key. If a key appears in a log, commit, or shared terminal, revoke it immediately. Requests using a revoked key return `401 invalid_api_key`.

The legacy `POST /api/keys/regenerate` endpoint still revokes every active default key and creates 1 replacement. Use it only when you intend to replace all default keys. Named integration keys and OAuth tokens are unaffected.

<span id="create-a-named-integration-key" />

## Manage an integration key

These account-management endpoints require a signed-in Pro or Max website session. A developer API key does not authenticate them.

| Action | Request |
| - | - |
| Create | `POST /api/keys/integrations` with `name`, `scope`, and `expires_in_days`. |
| List | `GET /api/keys/integrations`. |
| Rotate | `POST /api/keys/integrations/{integration_id}/rotate`. |
| Revoke | `DELETE /api/keys/integrations/{integration_id}`. |

For example, this creation body permits API reads and usage inspection, but excludes webhook management and exports:

```json theme={null}
{
  "name": "Reports",
  "scope": "read usage",
  "expires_in_days": 30
}
```

Creation returns the full key once and its stable `integration_id`. Rotation returns a new key and `overlap_ends_at`; switch consumers before that time.

The rotation overlap lasts 15 minutes. A `409` means a prior overlap is still active; wait for it to end or revoke the integration. Revocation stops both keys immediately.

Listing returns prefixes, scopes, expiry, last use, revocation, and monthly counts without exposing secrets. The default page has at most 100 rows, the maximum is 200, and `next_before_id` becomes the next request's `before_id`. Usage totals update every 5 minutes.

<span id="fix-an-auth-error" />

## Fix an authentication error

| Status and code | Cause | Action |
| - | - | - |
| `401 invalid_api_key` | Missing Bearer header, malformed, expired, rotated, or revoked credential. | Check the header and credential. A live API key has 76 characters. |
| `401`, reason `api_key_in_query` | A key was sent in the URL. | Use the `Authorization` header. |
| `401`, reason `sandbox_api_key` | A sandbox key was sent to production. | Use the sandbox URL or a live credential. |
| `402 subscription_required`, reason `subscription_inactive` | The credential is valid, but paid access is inactive. | Reactivate at [Billing](https://0xinsider.com/billing). Scheduled retries will not fix this. |
| `403 insufficient_scope` | The credential lacks a required scope. | Use a key with that scope, or obtain a new OAuth authorization. |
| `403 forbidden` | The account was deleted or the IP is blocked. | Contact [support](mailto:support@0xinsider.com). |
| `423 account_locked` | The account is locked. | Contact [support](mailto:support@0xinsider.com). |

<span id="what-a-key-does-not-do" />

## Limits

A 0xinsider credential cannot place a Polymarket order and contains no Polymarket trading credential. All of an account's API keys and OAuth tokens share its [rate limits](/rate-limits); creating another key does not create another allowance.


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