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

# Authentication

> API keys, OAuth client credentials, scopes, and session auth for OmniCommerce APIs.

OmniCommerce developer endpoints authenticate with bearer tokens. Prefer organization API keys for server-to-server integrations.

## API key (recommended)

Create a key in organization settings. Send it as:

```http theme={null}
Authorization: Bearer $OMNI_API_KEY
```

> [!NOTE]
>
> API keys are organization-scoped. Do **not** send `organizationId` for API-key
> requests. Session-authenticated UI calls still require `organizationId`.

API keys created from organization settings receive all developer scopes by default. Before creating the key, clear any permissions the integration does not need. You can edit the selected scopes later; changes take effect immediately, and regenerating the key preserves its permission set.

## OAuth client credentials

Machine clients can use:

```http theme={null}
POST /api/v1/oauth/token
```

and revoke with:

```http theme={null}
POST /api/v1/oauth/revoke
```

Request only the scopes your client needs. Common scopes include:

| Scope | Used by |
| - | - |
| `catalog:read` / `catalog:write` / `catalog:enrich` | Products, bulk import, ghost mannequin |
| `orders:read` / `orders:write` | Orders, order actions, shipping labels |
| `reviews:read` / `reviews:write` | Reviews, replies, AI generation |
| `analytics:read` | Analytics dashboards |
| `returns:read` | Return bootstrap and reconciliation |
| `settlements:read` | Settlement reconciliation |
| `webhooks:manage` | Subscriptions and event recovery |
| `promotions:read` / `promotions:write` | Promotions and campaigns |
| `price_books:read` / `price_books:write` | Price books |
| `aops:read` / `aops:write` | Agent operating procedures |
| `skills:read` | Read organization skill instructions |
| `agents:invoke` | General Omni agent |
| `documents:read` / `documents:write` | Knowledge-base search, reading, and uploads |
| `branding:read` / `branding:write` | Brand guidelines and brand-kit management |

For API-initiated enrichment, `skills:read` loads organization skills without requiring AOP access. New keys include this scope by default; custom scope selections can omit it during creation or later in key settings. Existing keys receive it through a one-time migration. Enable `documents:read` for knowledge-base evidence, and `branding:read` plus `branding:write` for brand-kit lookup and resolution. Resolution can create a missing brand kit. The general Omni agent uses `agents:invoke`. See [Omni agent API](https://docs.omnicommerce.ai/guides/agent.md).

Exact scope requirements are listed on each endpoint in the [API reference](https://docs.omnicommerce.ai/api-reference.md) and in the guides.

## Session auth (first-party UI)

Browser sessions (cookies) work for first-party OmniCommerce UI flows. Those requests must include `organizationId` in the query string (GET) or JSON/multipart body (writes).

[Direct script execution](https://docs.omnicommerce.ai/guides/scripts.md) through `/api/scripts/...` requires this app session and organization permissions. An OmniCommerce API key or OAuth token alone does not authenticate these routes. Windmill's native API uses a separate Windmill bearer token.

## Playground

The Mintlify API playground uses bearer auth. Paste your `omni_sk_...` key when using **Try it**. Prefer non-production keys when testing.

## Error responses

Unauthenticated or under-scoped requests return `401` / `403` with a JSON error body. Retry only after fixing credentials or scopes—do not spin on auth failures.


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