> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md). # Emporix Auth Use the emporix-auth skill to choose Emporix token types, request tokens, pick scopes, and interpret 401 and 403 responses. Use the **emporix-auth** skill to authenticate against the Emporix Commerce Engine API. It helps you pick the right token type, compose OAuth requests, choose minimal scopes, and diagnose `401` or `403` responses from `api.emporix.io`. {% hint style="info" %} This page explains when to use the skill and how to work with it. For endpoint details and OpenAPI security requirements, see the [OAuth Service](/api-documentation/api-guides/authentication/oauth-service.md) documentation, [Token exchange](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/quickstart/authentication/token-exchange), and the API reference for each call. For MCP credentials, see also [Retrieving Emporix MCP Token](/agentic-commerce-intelligence/mcp-in-emporix/mcp/retrieving-mcp-token.md). {% endhint %} ## Skill details | Property | Value | | ------------ | -------------------------------------------- | | Skill name | `emporix-auth` | | Package path | `skills/emporix-auth/` (contains `SKILL.md`) | Install it once using [Installing skills](/agentic-commerce-intelligence/agentic-engineering/skill-library.md#installing-skills). ## When to use it Use this skill when you need to: * Obtain or choose between Emporix token types (service access, anonymous, customer, SSO / token exchange, B2B legal-entity, MCP) * Compose OAuth token requests for integrations * Select minimal scopes for an API key or integration * Diagnose `401` or `403` responses from any `api.emporix.io` endpoint * Connect an AI tool to the hosted Emporix MCP server with the right MCP token packaging ## How it works Every Emporix API call is authorized with an OAuth 2.0 bearer token, except for MCP URL packaging, which embeds API key material. Endpoints declare which scopes the token must carry. The platform uses different token types for machine integrations, storefront guests, logged-in customers, and SSO. Walk the decision tree top-down; the first match wins. Base URL for token and API calls: `https://api.emporix.io`. Tenant names are lowercase. ```mermaid --- config: layout: fixed theme: base look: classic themeVariables: background: transparent lineColor: "#9CBBE3" arrowheadColor: "#9CBBE3" edgeLabelBackground: "#FFC128" edgeLabelTextColor: "#4C5359" --- flowchart TD Start["What are you calling?"] Backend{"Backend or
server-to-server?"} Mcp{"Hosted Emporix
MCP server?"} Guest{"Storefront guest
not logged in?"} Login{"Storefront login
email or password?"} Sso{"External IdP
SSO?"} Service["Service access token"] McpToken["MCP token"] Anon["Anonymous token"] Customer["Customer token"] SsoToken["SSO or token exchange"] Start --> Backend Backend -->|Yes| Service Backend -->|No| Mcp Mcp -->|Yes| McpToken Mcp -->|No| Guest Guest -->|Yes| Anon Guest -->|No| Login Login -->|Yes| Customer Login -->|No| Sso Sso -->|Yes| SsoToken Start@{ shape: rounded} Service@{ shape: rounded} McpToken@{ shape: rounded} Anon@{ shape: rounded} Customer@{ shape: rounded} SsoToken@{ shape: rounded} style Start fill:#F2F6FA,stroke:#4C5359,color:#4C5359 style Backend fill:#DDE6EE,stroke:#4C5359,color:#4C5359 style Mcp fill:#DDE6EE,stroke:#4C5359,color:#4C5359 style Guest fill:#DDE6EE,stroke:#4C5359,color:#4C5359 style Login fill:#DDE6EE,stroke:#4C5359,color:#4C5359 style Sso fill:#DDE6EE,stroke:#4C5359,color:#4C5359 style Service fill:#A1BDDC,stroke:#4C5359,color:#4C5359 style McpToken fill:#A1BDDC,stroke:#4C5359,color:#4C5359 style Anon fill:#A1BDDC,stroke:#4C5359,color:#4C5359 style Customer fill:#A1BDDC,stroke:#4C5359,color:#4C5359 style SsoToken fill:#A1BDDC,stroke:#4C5359,color:#4C5359 ``` | Token type | Typical use | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Service access | Backend, scripts, and CI. A machine caller uses the `client_credentials` grant. | | MCP | Hosted Emporix MCP server URL. The value is Base64 of the custom API key `clientId:secret` (not an OAuth access token). | | Anonymous | Storefront guest session; returns `sessionId` for cart continuity | | Customer | Storefront email/password login; authorize login with the anonymous bearer token first | | SSO / token exchange | External IdP. Use Emporix-managed authorization code **or** client-owned token exchange. Do not mix them. | | B2B (after customer or SSO) | Refresh the customer token with `legalEntityId` so the company context is embedded in the token | {% hint style="info" %} * B2B is not a separate first-choice token. After a customer or SSO token exists, refresh with `legalEntityId` when the shopper acts for a company. Switching companies means another refresh with the new `legalEntityId`, not a full re-login. * For storefront continuity, start with an anonymous token, then complete customer login while sending the anonymous bearer token, then merge the anonymous cart into the customer cart. Skipping a step can lose the guest cart. Customer tokens also return `saas_token` (needed for checkout) and a `refresh_token`. * Do not impersonate Management Dashboard employees from integrations. Use a service access token with restricted scopes instead. {% endhint %} ## Prerequisites Before you use this skill, make sure you have: * Emporix API credentials (Client ID and Secret) and, for storefront flows, Storefront API credentials (Client ID) * A custom API key with only the scopes your integration needs – recommended for production * A clear call pattern (backend, storefront, SSO, or MCP) so you can pick the matching token type ## How to use it After install, work in your AI tool with natural-language requests. Examples: > Get a service access token with only `currency.currency_read` for tenant `mytenant`. > Which token type do I need for a storefront guest who later logs in? > Why do I get `403` on this product update when my token call returned `200`? > Build an MCP server URL for the product domain with the right scopes. Provide your tenant name (lowercase), Client ID/Secret source, and the endpoint or MCP domain you are calling. ## Usage notes * Request **explicit scopes** on service tokens in production. Omitting `scope` grants every scope on the API key. * Service access tokens have no usable refresh token. When they expire, request a new one. Confirm tenant binding via `tenant=` in the token response `scope` string. * An MCP token packages a custom key that carries the MCP scope plus tool scopes; missing tools usually mean missing scopes on the key. Treat the MCP URL as a credential. See [Retrieving Emporix MCP Token](/agentic-commerce-intelligence/mcp-in-emporix/mcp/retrieving-mcp-token.md). * Custom API key scopes are fixed at creation. You cannot add scopes later; create a new key if needed. Some scopes cannot be attached to API keys at all. If a scope is not offered in the portal, contact [Emporix Support](mailto:support@emporix.com). * Requesting a scope the key does not carry still returns `200`; the missing scope is silently absent from the granted set. Always read back the `scope` field. * Prefer `_read` over `_manage`, and `_own` or type-specific scopes over tenant-wide ones. Take required scopes from each endpoint’s API reference. Do not invent scope names. * For SSO access, choose either Emporix-managed authorization code or token exchange. Never use both in one implementation. ### Checking status codes | Symptom | What it means | What to check | | ---------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Invalid ApiKey` when requesting a token | Gateway rejected `client_id` before OAuth | Confirm the Client ID in **Developer Portal** → **Manage API Keys**. Check the key is for the right environment and is not revoked. | | `401 Unauthorized` | Token rejected | Check whether the token has expired. Confirm you are using the right token type for the endpoint. Compare the `{tenant}` in the URL with `tenant=` in the token `scope` string. | | `403 Forbidden` | Valid token, missing scope | Compare the scopes granted on the token with the endpoint’s API reference. If a scope you requested is missing from the grant, create a new API key that includes it. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.