> ## 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

> Authenticate OrgX REST, MCP, and webhook integrations.

OrgX uses different authentication mechanisms for each public integration
surface.

| Surface             | Auth method         | Credential                      |
| ------------------- | ------------------- | ------------------------------- |
| REST Public Preview | API key             | `Authorization: Bearer oxk_...` |
| Hosted MCP          | OAuth 2.1 with PKCE | Client-managed access token     |
| Webhooks            | HMAC signature      | `X-OrgX-Signature`              |

## REST API Keys

REST Public Preview endpoints use user-scoped API keys. API keys begin with
`oxk_` and inherit the workspace access of the user who created them.

```bash theme={"dark"}
curl https://useorgx.com/api/client/bootstrap \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H "Accept: application/json"
```

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

## Create an API Key

1. Sign in to [OrgX](https://useorgx.com).
2. Open **Settings**.
3. Find **OrgX API keys**.
4. Generate a key for the integration or sandbox workspace.
5. Store the full key immediately. OrgX only shows it once.

The settings UI lists each key prefix, name, creation time, and last-used time.
Revoke keys from the same settings area when an integration is retired.

## Request Headers

| Header            | Required                        | Description                                                                                    |
| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `Authorization`   | Yes                             | `Bearer oxk_...`                                                                               |
| `Accept`          | Recommended                     | `application/json`                                                                             |
| `Content-Type`    | Required for JSON bodies        | `application/json`                                                                             |
| `OrgX-Version`    | Optional preview convention     | Contract date for integrations that pin a documented preview version, for example `2026-04-29` |
| `Idempotency-Key` | When documented by the endpoint | Unique key for retryable writes with server-side idempotency support                           |

## Workspace Scope

Every API key resolves to a user and workspace context. Route handlers enforce
that callers only read or write accessible resources. Do not pass arbitrary
`user_id` values in requests. API-key requests use the authenticated identity,
not a caller-provided identity.

## Failed Authentication

Missing, revoked, malformed, or invalid keys return `401`.

```json theme={"dark"}
{
  "error": "Unauthorized",
  "message": "Valid API key required. Get your key from OrgX settings."
}
```

## MCP OAuth

The hosted MCP server uses OAuth 2.1 with browser-based authorization and PKCE.
Remote MCP clients discover the auth server through protected-resource metadata
and manage token refresh automatically.

```text theme={"dark"}
https://mcp.useorgx.com/mcp
```

Use MCP OAuth for AI clients and MCP Apps. Use REST API keys for server-side
system integrations and local runtime bridges.