{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img","admonition"]},"type":"markdown"},"seo":{"title":"Authorization","description":"Find answers to your technical questions and learn how to integrate Mirakl products.","lang":"en-US","siteUrl":"https://developer.mirakl.com/","keywords":"mirakl, documentation, api","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authorization","__idx":0},"children":["Authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every call your connector makes to the Mirakl Connect Channel Platform REST APIs is authenticated."," ","This page describes the mechanism that secures those calls:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["how to obtain an access token,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["how to present it on each request,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["how to keep it fresh."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The events you receive carry no token of their own."," ","Mirakl Connect publishes them to the queue or the topic you own, and you grant it the permission to publish there."," ","Refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/receiving-events#choosing-a-destination"},"children":["Receiving events"]},"."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/authorization.8f77532536d282e7931b34c75d1be7bf638ed8331f92af4f5122eb8bbe62c5e7.0929514f.png","alt":"Authorization","framed":false,"withLightbox":false,"width":"80%","height":"80%","align":"center"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-mechanism-oauth2-client-credentials","__idx":1},"children":["The mechanism: OAuth2 client credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mirakl Connect uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth2 client-credentials grant"]},"."," ","Your connector is a confidential client that acts as itself, with no end user involved."," ","It therefore authenticates with a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client ID"]}," and a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client secret"]},", and exchanges them for a short-lived ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["access token"]},"."," ","It then presents that token as a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer token"]}," on every REST call."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three facts define the whole flow:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mirakl issues you a client ID and a client secret."]}," ","Mirakl provisions them for you, and you do not register yourself."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You exchange them for a token at the token endpoint."]}," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth/token"]}," endpoint of the Mirakl Authentication System, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type=client_credentials"]}," and your credentials, returns a Bearer access token and its lifetime."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You send the token on every request."]}," ","Each REST call carries the header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer "]},"."," ","A request without a valid, unexpired token is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same client-credentials mechanism, and the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer"]}," header, secure both hosts your connector talks to: the Mirakl Connect host and the Mirakl Account host."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/environments"},"children":["Environments"]}," lists the host URLs for each environment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requesting-the-api-credentials","__idx":2},"children":["Requesting the API credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you start, request a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client ID"]}," and a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client secret"]}," from your contact in the Mirakl Partner team."," ","Store these credentials securely, because they let your connector generate the access token."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generating-and-using-the-access-token","__idx":3},"children":["Generating and using the access token"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"generating-the-access-token","__idx":4},"children":["Generating the access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To obtain the access token, call the Mirakl Authentication System:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Method: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.mirakl.net/oauth/token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Content-Type: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parameters, all of them mandatory:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]},": must be equal to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},": your client ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},": your client secret"]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint above is the production host."," ","In the test environment, use the test authentication host listed in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/environments"},"children":["Environments"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token request is a standard client-credentials exchange, sent as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /oauth/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=client_credentials&client_id=&client_secret=\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If everything works as expected, the Mirakl Authentication System generates an access token and returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," status, with a JSON response structured as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"token_type\": \"Bearer\",\n \"access_token\": \"***********\",\n \"expires_in\": 3599,\n \"target_app\": \"\",\n \"resource_owner\": \"\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three fields matter:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_type"]},": always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]}," in this workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},": the Bearer token you present on every REST call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]},": the token's remaining lifetime, in seconds."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build your connector's caching and refresh logic around ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]},", and request a new token a few minutes before it elapses."," ","Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#token-lifecycle"},"children":["Token lifecycle"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-the-access-token","__idx":5},"children":["Using the access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every REST call to the Channel Platform presents the token on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://miraklconnect.com/api/channel-platform/\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"...\": \"request body\" }\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scopes","__idx":6},"children":["Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access is not all or nothing."," ","Tokens carry ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["fine-grained scopes, one for each operation"]},", and each REST operation declares the scope it requires."," ","Scopes follow the pattern ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform::"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These examples come from the current API surface:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform:store:write"]}," grants the right to publish a store's business information."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform:channel-catalog:configure"]}," grants the right to configure a channel's catalog and taxonomy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform:orders:upsert"]}," grants the right to synchronize the orders."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform:order-action:upsert"]}," grants the right to report the outcome of an order action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect-channel-platform:order-returns:upsert"]}," grants the right to synchronize the returns."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your credentials are authorized for the scopes your connector needs, and the token you receive carries those scopes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}," rather than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", the token was valid but it did not carry the scope the operation requires."," ","That is a problem of authorization, not of authentication."," ","To resolve it, ask your Mirakl partner contact to adjust the scopes associated to your OAuth2 client."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"token-lifecycle","__idx":7},"children":["Token lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access tokens are short-lived by design."," ","Build your connector to obtain a token once, reuse it across many calls, and refresh it only as it nears its expiry."," ","Do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," request a fresh token for each call."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cache the token."]}," ","Keep the access token and its expiry in memory, or in shared storage if several worker processes call the API."," ","Reuse it for every call until it is close to its expiry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refresh ahead of the expiry."]}," ","Treat the token as expired slightly before its real deadline, so that a request never fails in flight on a token that lapses in transit."," ","A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["leeway of about 300 seconds, which is 5 minutes"]},", before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," is a safe margin."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refresh on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"."]}," ","If a call is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}," even so, discard the cached token, request a new one, and retry the call once."," ","This covers clock skew, and tokens revoked before their nominal expiry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Serialize the refreshes."]}," ","If many calls run concurrently, make sure that only one refresh happens at a time, rather than every caller requesting its own token when the cached one lapses."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-flow-end-to-end","__idx":8},"children":["The flow end to end"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","diagramType":"mermaid","diagramSource":"sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant AS as Mirakl Auth System\n participant API as Channel Platform API\n end\n box rgb(209,250,229) Middleware\n participant C as Channel Connector\n end\n\n Note over C: No valid token cached\n C->>AS: POST /oauth/token (client id + secret)\n AS-->>C: access_token + expires_in\n Note over C: Cache token until (expiry - 300s)\n\n C->>API: Request + Authorization: Bearer \n API-->>C: 200 / 202 / 204\n\n Note over C: Later, the cached token is still fresh\n C->>API: Another request (reuse cached token)\n API-->>C: 200 / 202 / 204\n\n Note over C: Token expired or revoked\n C->>API: Request + Authorization: Bearer \n API-->>C: 401 Unauthorized\n C->>AS: POST /oauth/token (refresh)\n AS-->>C: new access_token + expires_in\n C->>API: Retry request + Bearer \n API-->>C: 200 / 202 / 204\n","diagramHtml":"MiddlewareMiraklChannel ConnectorChannel Platform APIMirakl Auth SystemChannel ConnectorChannel Platform APIMirakl Auth SystemNo valid token cachedCache token until (expiry - 300s)Later, the cached token is still freshToken expired or revokedPOST /oauth/token (client id + secret)access_token + expires_inRequest + Authorization: Bearer <token>200 / 202 / 204Another request (reuse cached token)200 / 202 / 204Request + Authorization: Bearer <expired>401 UnauthorizedPOST /oauth/token (refresh)new access_token + expires_inRetry request + Bearer <new token>200 / 202 / 204","diagramHtmlDark":"MiddlewareMiraklChannel ConnectorChannel Platform APIMirakl Auth SystemChannel ConnectorChannel Platform APIMirakl Auth SystemNo valid token cachedCache token until (expiry - 300s)Later, the cached token is still freshToken expired or revokedPOST /oauth/token (client id + secret)access_token + expires_inRequest + Authorization: Bearer <token>200 / 202 / 204Another request (reuse cached token)200 / 202 / 204Request + Authorization: Bearer <expired>401 UnauthorizedPOST /oauth/token (refresh)new access_token + expires_inRetry request + Bearer <new token>200 / 202 / 204"},"children":["sequenceDiagram\n box rgb(219,234,254) Mirakl\n participant AS as Mirakl Auth System\n participant API as Channel Platform API\n end\n box rgb(209,250,229) Middleware\n participant C as Channel Connector\n end\n\n Note over C: No valid token cached\n C->>AS: POST /oauth/token (client id + secret)\n AS-->>C: access_token + expires_in\n Note over C: Cache token until (expiry - 300s)\n\n C->>API: Request + Authorization: Bearer \n API-->>C: 200 / 202 / 204\n\n Note over C: Later, the cached token is still fresh\n C->>API: Another request (reuse cached token)\n API-->>C: 200 / 202 / 204\n\n Note over C: Token expired or revoked\n C->>API: Request + Authorization: Bearer \n API-->>C: 401 Unauthorized\n C->>AS: POST /oauth/token (refresh)\n AS-->>C: new access_token + expires_in\n C->>API: Retry request + Bearer \n API-->>C: 200 / 202 / 204\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rotating-credentials","__idx":9},"children":["Rotating credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["access token"]}," rotates automatically, because it is short-lived and your connector fetches it again as described above."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client secret"]}," is a long-lived credential."," ","Treat it like any other secret: store it encrypted, never commit it to source control, never log it, and rotate it periodically."," ","Your contact in the Mirakl Partner team issues a new client secret."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-pages","__idx":10},"children":["Related pages"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/calling-the-apis"},"children":["Calling the APIs"]},": where to present the token, and the two hosts the calls are split across."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/prerequisite-resources"},"children":["Get access"]},": how you obtain the client credentials in the first place."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/getting-started/environments"},"children":["Environments"]},": the test and production token endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/content/product/connect-channel-platform/developer-guide/best-practices"},"children":["Best practices"]},": how to handle a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," against a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", and what to log about each."]}]}]},"headings":[{"value":"Authorization","id":"authorization","depth":1},{"value":"The mechanism: OAuth2 client credentials","id":"the-mechanism-oauth2-client-credentials","depth":2},{"value":"Requesting the API credentials","id":"requesting-the-api-credentials","depth":2},{"value":"Generating and using the access token","id":"generating-and-using-the-access-token","depth":2},{"value":"Generating the access token","id":"generating-the-access-token","depth":3},{"value":"Using the access token","id":"using-the-access-token","depth":3},{"value":"Scopes","id":"scopes","depth":2},{"value":"Token lifecycle","id":"token-lifecycle","depth":2},{"value":"The flow end to end","id":"the-flow-end-to-end","depth":3},{"value":"Rotating credentials","id":"rotating-credentials","depth":2},{"value":"Related pages","id":"related-pages","depth":2}],"frontmatter":{"seo":{"title":"Authorization"}},"lastModified":"2026-08-28T13:10:01.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/content/product/connect-channel-platform/developer-guide/authorization","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}