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

# Authentication

> Use one server-side API key across authenticated workspace operations.

Published workspace operations accept an OrgX API key:

```http theme={"dark"}
Authorization: Bearer oxk_...
```

The key resolves the user and workspace. Request bodies do not need a
`workspace_id` unless an operation explicitly supports choosing among multiple
workspaces.

## Create a key

1. Sign in to [OrgX Settings](https://useorgx.com/settings).
2. Open **OrgX API keys**.
3. Create a key and store the full value when it is shown.

<Warning>
  API keys are server-side secrets. Do not expose them in browser code, mobile
  applications, public repositories, logs, or screenshots.
</Warning>

## Send the key

Every shell example in these docs reads the key from an environment variable so
that no page invites you to paste a literal secret:

```bash theme={"dark"}
export ORGX_API_KEY='oxk_...'
```

```bash theme={"dark"}
curl https://useorgx.com/api/v1/work \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-work-001' \
  -d '{"title":"Review the launch plan"}'
```

Missing, malformed, revoked, or invalid keys return `401` with the standard
error envelope:

```json theme={"dark"}
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required",
    "requestId": "req_01J5YB8X4Y"
  }
}
```

## Use the API playground

Open an operation page, select **Authorize**, and paste the API key. Playground
requests call the production API and can create real workspace data, so use a
dedicated test workspace for exploratory writes.

Account-free receipt validation, workload diagnosis, and showcase reads do not
need a key. Stripe authenticates its callback with `stripe-signature`.

## Conventions used across these docs

| Convention     | Form                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------ |
| Auth header    | `Authorization: Bearer oxk_...` on the wire; `Bearer $ORGX_API_KEY` in every shell example |
| Base URL       | `https://useorgx.com/api/v1` for published REST operations                                 |
| Mutations      | `Idempotency-Key` header on writes                                                         |
| Error envelope | `{ "error": { "code", "message", ... } }` with lowercase `snake_case` codes                |

Base URLs are always spelled `useorgx.com` — never `www.useorgx.com`.

AI clients use [MCP OAuth with PKCE](/docs/api/mcp-protocol) instead of REST API keys.

<Note>
  The older `/api/entities` route remains available as a compatibility adapter
  for existing workspace and MCP clients. It is not the v1 contract; new
  integrations should not depend on it.
</Note>