Skip to content
Products
/
/
/
Channel authorization

Channel authorization

Before any data flow can run for a seller, that seller must grant your connector access to their account on the channel. This page covers the whole process end to end:

  • how to obtain that consent,
  • how to hold the credentials it produces,
  • how to import the seller's stores in Mirakl Connect,
  • how to renew an authorization that expires.

How it fits

Channel authorization is the first flow to run for any seller, and nothing else runs for that seller until it completes. It is also the only flow a seller drives interactively. The seller moves through it in their browser, redirected between Mirakl, your connector, and the channel.

Two Mirakl hosts take part, and the diagrams below name them apart:

  • Mirakl Connect is where the seller starts the process, and where the seller returns at the end.
  • Mirakl Account issues the token, and serves the operation that imports the stores.

When the seller starts the process, Mirakl Account issues a token and passes it to your connector, and that token authorizes the store import at the end of the process. The two cannot happen independently: without consent there is no token, and without the token the seller's stores cannot be created. Refer to Stores for what a store is, and for its lifecycle once it exists.

Authorization mechanisms

The mechanism that grants access to the channel belongs to the channel, and Mirakl Connect does not constrain it. Whatever the channel offers, such as an OAuth2 flow, a seller who pastes an API key, or a signed delegation, your connector drives that exchange itself and holds the credentials it produces.

Two consequences follow:

  • The channel credentials stay with your connector. Nothing in this process sends them to Mirakl Connect. Your connector must store them securely for each seller, and present them on every later call to the channel.
  • Whether they expire is the channel's choice. When a channel issues credentials that expire, your connector must also expose an endpoint that the seller can use to renew them. Refer to Renewing an expiring authorization.

A seller can start the process either from Mirakl Connect or from the channel. Both paths end at the consent URL of the connector. There, the connector runs the channel's authorization process and saves the credentials it needs to access the channel data.

In both methods, the step numbers are the arrow numbers of the diagram. One step can cover several arrows.

Mirakl Connect method

In this method, the seller starts from their Mirakl Seller Account.

ChannelMiddlewareMiraklSellerChannelChannel ConnectorMirakl AccountMirakl ConnectChannelChannel ConnectorMirakl AccountMirakl ConnectSellerChannels > My Channels, then "Link stores"1Select the channel to import stores from2Request the consent redirection (callback)3Consent URL (token, callback)4Redirect to /consent (token, callback)5/consent6Run the channel authorization mechanism7Channel credentials8Save the credentials for this seller9Import the seller's stores (token)10Redirect to the callback URL11Mirakl Connect stores page12Seller
ChannelMiddlewareMiraklSellerChannelChannel ConnectorMirakl AccountMirakl ConnectChannelChannel ConnectorMirakl AccountMirakl ConnectSellerChannels > My Channels, then "Link stores"1Select the channel to import stores from2Request the consent redirection (callback)3Consent URL (token, callback)4Redirect to /consent (token, callback)5/consent6Run the channel authorization mechanism7Channel credentials8Save the credentials for this seller9Import the seller's stores (token)10Redirect to the callback URL11Mirakl Connect stores page12Seller

A dashed arrow is a response back to the caller, including an HTTP redirect.

Follow these steps:

  • Step 1: the seller signs in to Mirakl Connect, selects Channels > My Channels in the menu, then clicks the Link stores button.
  • Step 2: the seller selects the channel to import the stores from.
  • Steps 3 and 4: Mirakl Connect asks Mirakl Account for the consent redirection, and Mirakl Account issues the token.
  • Step 5: Mirakl Connect redirects the seller to the consent URL of the connector, /consent. It carries two query parameters:
    • token: authorizes the store import at the end of the process. Refer to The token.
    • callback: the callback URL of Mirakl Connect.
  • Steps 6 to 9: the connector receives the consent request, runs the channel's authorization process, and saves the credentials to access the channel data. This process can differ from one channel to another.
  • Step 10: the connector imports the seller's stores in Mirakl Account, as described in Importing the stores.
  • Steps 11 and 12: the connector redirects the seller to the Mirakl Connect stores page, by loading the callback URL given at the start of the process.

Channel method

In this method, the seller starts from the channel.

ChannelMiddlewareMiraklSellerChannelChannel ConnectorMirakl AccountMirakl ConnectChannelChannel ConnectorMirakl AccountMirakl ConnectSellerEnter the process from the channel1Redirect to the registered Channel Connector URL2/login3Redirect to /organizations/connectors (connector, state)4Choose the organization5Redirect to /consent (token, callback, state)6/consent7Run the channel authorization mechanism8Channel credentials9Save the credentials for this seller10Import the seller's stores (token)11Redirect to the callback URL12Mirakl Connect stores page13Seller
ChannelMiddlewareMiraklSellerChannelChannel ConnectorMirakl AccountMirakl ConnectChannelChannel ConnectorMirakl AccountMirakl ConnectSellerEnter the process from the channel1Redirect to the registered Channel Connector URL2/login3Redirect to /organizations/connectors (connector, state)4Choose the organization5Redirect to /consent (token, callback, state)6/consent7Run the channel authorization mechanism8Channel credentials9Save the credentials for this seller10Import the seller's stores (token)11Redirect to the callback URL12Mirakl Connect stores page13Seller

A dashed arrow is a response back to the caller, including an HTTP redirect.

Follow these steps:

  • Steps 1 to 3: the seller enters the process from the channel, usually from the page of your app in the channel's app store. The channel sends the seller to a connector URL that you registered with it, and this page uses /login as an example. Its query parameters are specified by the channel. Nothing is authorized at this point, because this is only the entry point. The channel authorization itself runs at Steps 8 to 10.
  • Step 4: the connector redirects the seller to the organizations URL of Mirakl Account, /organizations/connectors, so that the seller can choose an organization. It carries two query parameters:
    • connector: a String, the channel ID that the Mirakl partner team provides.
    • state: a String, a random value that your connector generates. Mirakl Account never reads its content, and returns it unchanged in the consent URL at Step 6. Store the context that /login received under this value, then read that context again when the seller reaches /consent. This is how your connector matches the consent request with the entry point that started the process. A random value also lets your connector reject a consent request it did not start.
  • Step 5: the seller chooses the organization.
  • Step 6: Mirakl Account issues the token, and redirects the seller to the consent URL of the connector, /consent. It carries three query parameters:
    • token: authorizes the store import at the end of the process. Refer to The token.
    • callback: the callback URL of Mirakl Connect.
    • state: the value your connector sent at Step 4, returned unchanged.
  • Steps 7 to 10: the connector receives the consent request, runs the channel's authorization process, and saves the credentials to access the channel data. This process can differ from one channel to another.
  • Step 11: the connector imports the seller's stores in Mirakl Account, as described in Importing the stores.
  • Steps 12 and 13: the connector redirects the seller to the Mirakl Connect stores page, by loading the callback URL given at the start of the consent phase.

The token

Mirakl Account issues a token when the seller starts the consent process, and passes it to your connector as the token query parameter of the consent URL. That token authorizes the one call that imports the seller's stores.

Four rules govern the token:

  • It expires. By default, the token is valid for 24 hours from the moment Mirakl Account issues it. The lifetime is configured for each connector, so confirm the value that applies to yours with your contact in the Mirakl Partner team.
  • It works once. The first successful store import consumes the token, and a later call that presents the same token is rejected.
  • It identifies the seller. Mirakl Account resolves the token to the seller who started the process, so your connector never sends a seller identifier of its own. Import all the stores of that seller in the single call the token allows.

Two constraints follow:

  • The lifetime rules out a deferred import in a job that runs after the token has expired.
  • The single use rules out an import of the stores in batches.

A 410 Gone response means that the token has expired, that it has already been used, or that it is unknown. Do not retry. The seller must restart the consent process from Mirakl Connect.

The import is atomic: the token is consumed only if the call succeeds. A 5xx response or a network timeout therefore leaves the token usable, so it is safe to retry that same call with that same token. The stores are upserted, so a retry cannot create duplicates.

Importing the stores

By this point, the connector holds the channel credentials. It can therefore fetch the seller's stores from the channel and create them with the sellerAccountStoreCreate API, which the Mirakl Account host serves, and pass the token in the token query parameter. The same call imports the seller's new stores after an authorization renewal.

Each store in the call requires a state. Refer to The store's state for the values and their meaning.

Send every store the seller holds on the channel in this one call. The first successful import consumes the token, so there is no second call to add the stores you left out. A store you omit here reaches Mirakl Connect only the next time the seller goes through the consent or the renewal.

Once the stores are created, the connector redirects the seller to the callback URL given at the start of the process, which returns them to the Mirakl Connect stores page. The seller can then link a store to activate its synchronization flows, as described in Stores.

For more information, refer to the REST APIs reference.

Renewing an expiring authorization

On some channels, the authorization to access the channel APIs expires, and the seller must renew it. In this case, your connector must provide an endpoint that lets the seller renew the channel authorization for a store.

The renewal repeats the consent process, with fewer steps. The seller returns through a redirect, Mirakl Account issues a new token under the same rules, and the connector runs the channel authorization again and imports the stores that the renewed credentials expose.

  • Step 1: the seller selects the store that needs an authorization renewal in Mirakl Connect and clicks the renew button. Mirakl Account then issues the token, and Mirakl Connect redirects the seller to the renew URL of the connector, /renew. It carries two query parameters:
    • token: authorizes the store import at the end of the process. Refer to The token.
    • callback: the callback URL of Mirakl Connect.
  • Step 2: the connector starts the channel's authorization process and saves the new credentials to access the channel data. This process can differ from one channel to another.
  • Step 3: the connector imports the seller's new stores, as described in Importing the stores.
  • Step 4: the connector redirects the seller to the Mirakl Connect stores page, by loading the callback URL given at the start of the process.
  • Stores: what a store is, and its lifecycle once this process has created it.
  • Authorization: the OAuth2 access token that authenticates the REST calls of your connector, which is separate from the token this process issues.
  • Business use cases: where this process fits among the flows you implement.
  • Data model: the definition, field by field, of the entities these flows carry.