Connect flow

When connecting to our services, you will go through a OAuth flow. This is to make the API as secure as possible.

Note: It is both possible to do a connect flow from a frontend application and a backend service. For security reasons we recommend you to, use a backend service for this. Then you can share the access_token with the frontend application if you want it to communicate directly with the headless API.

To start the Connect flow and start adding products to a basket, call the endpoint by doing the following:

    
        curl -D- -G \
            https://umbracodemo1.ucommerce.net/api/v1/oauth/connect \
            -d client_id=<CLIENT_ID> \
            -d redirect_uri=<REDIRECT_URL> \
            -d response_type=code 
    

The response will be a 302 (Found or Moved Temporarily). Please look in the location header and copy the code param.

Access token retrieval

Once you have called api/v1/connect, you can find a code in the Location header, which you will need to gain an access_token

Note: The code is not URL safe, meaning that it will be URL encoded. The code will need to be URL-decoded before the next step. Some web frameworks might do that automatically.

Authorization header in api/v1/oauth/token

The Authorization header in /oauth/token endpoints uses Basic HTTP Authentication scheme (which is defined in rfc7617). In other words, the value of the header is Basic {":" string encoded as base64}. Here’s a code example how to do in C#:

    public string GenerateBasicAuthorizationHeaderValue(string clientId, string clientSecret)
    {
        string credentials = $"{clientId}:{clientSecret}";
        byte[] credentialsByteData = Encoding.GetEncoding("iso-8859-1").GetBytes(credentials);
        string base64Credentials = Convert.ToBase64String(credentialsByteData);
        return $"Basic {base64Credentials}";
    }
    
    

Keeping state

Keeping state in a multi-tenant application is essential. This is super easy to do without a connect flow, as we allow you to choose how you want to do it.

Wildcard

We support wildcards in all of your redirect URLs. But what exactly is a wildcard and how do you use it?

A wildcard is a catch-all functionality that is very simple. Just place an * in your registered redirect URL ex. https://umbracodemo1.ucommerce.net/*

Note: We do not support wildcard in domain and sub-domain.

OAuth State

The primary reason for using the state parameter is to mitigate CSRF attacks. You can also use the state parameter to encode an application state that will round-trip to the client application after the connect flow is complete.

    
    curl -G \
      https://umbracodemo1.ucommerce.net/api/v1/oauth/connect \
      -d client_id=<CLIENT_ID> \
      -d redirect_uri=<REDIRECT_URL> \
      -d response_type=code  \
      -d state={your_state}