> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.sg/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`.
</Note>

API keys created from organization settings receive all developer scopes by default.

## 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                                 |
| `promotions:read` / `promotions:write`              | Promotions                             |
| `price_books:read` / `price_books:write`            | Price books                            |

Exact scope requirements are listed on each endpoint in the [API reference](/api-reference) 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).

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