Skip to content

authentication.md

Latest commit

 

History

History
75 lines (58 loc) · 2.47 KB

authentication.md

File metadata and controls

75 lines (58 loc) · 2.47 KB

Authentication

The majority of API requests must be authenticated via a JWT bearer token and a X-Customer-Context header.

X-Customer-Context: ...vyVMCy1ZFjhTWub3QW6aJzKqPi...
Authorization: Bearer ...eyJhbGciOiJIUzI...

Known Customers

Customers must authenticate via an external identity provider, such as Entra ID or Okta. The bearer token returned by the external provider is then used by all the api requests.

Anonymous Users

Users are 'anonymous' until they authenticate via an external provider. In this scenario, a request to the endpoint /commerceapi/authentication/ is required to create a bearer token for the anonymous user. The jti claim will hold the anonymous ID.

To maintain a consistent anonymous ID between subsequent authentication requests, you must include in the request body the current ID. This will be returned instead of generating a new ID.

POST /commerceapi/authentication/ HTTP/1.1
X-Auth-Key: ...2ODQ5NDg1MGEzYzI4MGFkZGE2M...
{
    "anonymousAuthenticationRequest": "{{$guid}}"
}

This returns a bearer token that can be used by all the api requests

{
  "tokenType":"Bearer",
  "accessToken":"...eyJhbGciOiJIUzI1NiIsInR5cCI6I...",
  "expiresIn":7200,
  "refreshToken":""
}

Note: The value in the X-Auth-Key header must match the appSetting JhooseCommerceApiOptions.AuthorizationKey.

Once the user has authenticated, the next step is to create the customer context.

Note: When the authentication token expires and is recreated, you must also recreate the customer context.

Customer Context

The customer context is a secure token which provides additional information about the customer.

The customer content provides a mechanism for validating the customer against the authenticated user.

GET /commerceapi/authentication/customercontext HTTP/1.1
Authorization: Bearer ...eyJhbGciOiJIUzI1NiIsInR5cCI6I...
{
    "isAnonymous": true,
    "customerContext": "...vyVMCy1ZFjhTWub3QW6aJzKPQlOm17..."
}

Migrate Cart

When a user authenticates it is important to maintain the state of the cart. To support this journey you must call the cart migrate endpoint.

The Customer context must be for the newly authenticated user, and the anonymousId is from the previoud state.

POST /commerceapi/cart/migrate HTTP/1.1
X-Customer-Context: ...vyVMCy1ZFjhTWub3QW6aJzKqPi...
Authorization: Bearer ...eyJhbGciOiJIUzI...
{
    "anonymousId": "...a12d-4356..."
}