Skip to main content
OmniCommerce developer endpoints authenticate with bearer tokens. Prefer organization API keys for server-to-server integrations. Create a key in organization settings. Send it as:
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:
and revoke with:
Request only the scopes your client needs. Common scopes include: 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. Exact scope requirements are listed on each endpoint in the 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). Direct script execution 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.