Authentication

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

Published workspace operations accept an OrgX API key:

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.
2. Open OrgX API keys.
3. Create a key and store the full value when it is shown.

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

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:

export ORGX_API_KEY='oxk_...'

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:

{
  "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 instead of REST API keys.

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.