Weblink API Authorization

Weblink API requests can be made as a guest or authenticated user.

In the following examples <portalBaseUrl> refers to the base URL of your WebLink portal, such as mycompany-store.administrateweblink.com.

Guest user

This method relies on a Portal token in the Authorization header of all WebLink API requests. Not only this makes it possible to execute queries with WebLink API but it also ensures that any Carts created with this Portal token can only be queried or modified by API requests with the same token.

If you are using the WebLink API to customize the Catalog and Shopping Cart experience and take the user to our hosted solution to complete the order, this is the easiest approach.

Obtain a Portal token

Make a POST request to https://portal-auth.administratehq.com/portal/guest with a JSON body like the below:

{
    "domain": "<portalBaseUrl>"
}

CURL example:

curl 'https://portal-auth.administratehq.com/portal/guest' \
  -X POST \
  -H 'Content-Type: application/json;charset=utf-8' \
  --data-raw '{"domain": "<portalBaseUrl>"}'

The response will contain the <guestToken> that must be used for subsequent requests. This should be stored on the client and will be valid for 1 hour

{
    "portal_token": "<guestToken>"
}

Required headers

The portal token must be specified in all subsequent request headers, alongside the weblink-portal header:

IMPORTANT: all subsequent API requests should use the same token to ensure you can create, modify and check out the shopping cart. If the token expires or is refreshed, a new shopping cart must be created.

Authenticated user

This method ensures that purchases are associated to a specific user identity, which is managed by our Identity Provider (IDP) with credentials stored in the TMS. Our Identity Provider is OpenID Connect and OAuth2 compliant, and it is also possible to configure it to rely on your own provider or a 3rd party.

We recommend using a library encapsulating the complexity, such as Auth0.

It is possible to start a user session as Guest using a Portal token, and switch the session to authenticated at any point during the user journey.

Preliminaries

Get the IDP configuration from our Host lookup service on this URL

https://host-lookup.getadministrate.com/portal_config?host=<portalBaseUrl>

The response will contain the following relevant data:

{
  "brand": "<brandId>",
  "idp": {
    "client_id": "<clientId>",
    "domain": "<domain>"
  }
 }

Start the authorization flow

Code verifier and challenge

The code verifier is a random, unique string that you need to generate and store temporarily in your session to complete the flow in the following steps. To create the code challenge, you need to create a SHA256 hash of the verifier, and base64 URL encode it. More information and recommendations

Example (Python):

from base64 import urlsafe_b64encode
import hashlib

code_verifier = "unique_and_r@nd0M!_string"
code_challenge = urlsafe_b64encode(                     # Result: "Ia6CrXEp0F-eOk_i1JHCLF_LkHW4zBoRYBADp6b0kjg"
    hashlib.sha256(code_verifier.encode()).digest()
).decode().replace("=", "")

Redirect to the IDP

You will now have to redirect the user to the IDP substituting the parameters <brandId>, <clientId> and <code_challenge> with the values obtained in the previous steps. The <redirectUri> is a URL on your website where the user should be redirected to after logging in.

https://<domain>/authorize?brand=<brandId>
                          &client_id=<clientId>
                          &code_challenge=<code_challenge>
                          &redirect_uri=<redirectUri>

The user will be taken to the IDP to sign in and will be redirected to the URL you specified.

Obtain an Access token

The redirection URL will contain a code parameter in the query string. A POST request to https://<domain>/token must be made with this code and the <code_verifier> from the previous step:

{
  "code": "<code>",
  "client_id": "<clientId>",
  "code_verifier": "<code_verifier>"
}

The response will contain the JWT tokens:

{
  "access_token": "<accessToken>",
  "id_token": "<idToken>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refreshToken>"
}

where

• accessToken is the token that will have to be sent in the Authorization header in subsequent WebLink API requests
• refreshToken allows obtaining a new Access token once it expires
• expires_in is the number of seconds the access token is valid for (default: 1 hour)
• idToken contains some user identity information (name, email etc.)

You can verify the authenticity of these using our Identity Provider public key These JWT tokens can be decoded (see specification and playground) to extract information. For example a decoded ID token contains the following

{
  "iss": "https://identity.getadministrate.com/",
  "sub": "mycompany:contact:UGVyc29uOjI2NDI=",
  "aud": "weblink2ui",
  "exp": 1681138664,
  "iat": 1665413864,
  "email": "test@example.com",
  "given_name": "Jane",
  "family_name": "Smith"
}

Set WebLink API authorization headers

The Access token must be specified in all subsequent request headers, alongside the weblink-portal header:

The access_token is valid for 1 hour. You may wish to set up a method to obtain a fresh token past the expiry time, using the refresh_token