Skip to main content

Authentication

Introduction​

Spaaza supports three different authentication methods, with two sub-methods for user authentication. These allow users, admin users and privileged clients such as trusted 3rd parties to consume the Spaaza API.

User Authentication​

User authentication is used for end-user sessions. An end-user is almost invariably a customer or member of a programme - an example is when a customer logs into a mobile app with their account, then the mobile app stores the resulting session information and uses it to make further requests to the Spaaza API.

End-user authentication is available for various API endpoints. The standard user authentication method uses HTTP headers containing user ID and session key values obtained via the login API endpoint. The following headers must be passed to any API endpoint using standard user authentication:

  • X-Spaaza-Session-User-Id: user ID of the user obtained via the login endpoint
  • X-Spaaza-Session-Key: session key of the session obtained via the login endpoint
  • X-Spaaza-MyPrice-App-Hostname: hostname of the Spaaza app the user is affiliated with

Spaaza is often configured to pass end-user authentication requests through to a 3rd party authentication service such as an e-commerce or identity API, meaning end-user authentication details do not need to be kept in Spaaza's data store.

Two alternative sub-methods are available for end-user authentication, as described below.

JWT Access Token Authentication​

For integrations where the client already has a JWT access token issued by a trusted identity provider, the standard session-based headers can be replaced by a single JWT header. This allows the client to authenticate end-users without calling the Spaaza login endpoint or maintaining Spaaza session state.

The following header is used:

  • X-Spaaza-Access-Token-JWT: a signed JWT access token containing the end-user's identity

The X-Spaaza-MyPrice-App-Hostname header is also required to identify the Spaaza app context for the request.

JWT access token authentication is stateless: each request is independently verified against the chain's configured trust settings (JWKS URL, issuer, and optionally audience). No server-side session is created or persisted.

For full details on the JWT access token format, required claims, chain configuration, and scope enforcement, see JWT Access Token Authentication.

Shopify User Authentication​

For Shopify integrations, the standard X-Spaaza-Session-User-Id and X-Spaaza-Session-Key headers are replaced by a set of Shopify-specific headers that allow the storefront to authenticate customers without calling the Spaaza login endpoint. These headers use the Shopify customer ID and an HMAC-SHA256 hash derived from shop or customer metafields set up during the Spaaza app installation.

For full details on the Shopify-specific authentication headers and how to construct them, see Authenticating Shopify Users.

Admin Authentication​

Admin user authentication is available for various API endpoints. An admin user is a user with permission to create, update, delete, or assign information for a particular Spaaza app or retailer. An example might be API requests made by a service running at head office, or by a point of sale device (POS) in a store.

Admin authentication uses HTTP headers containing the user ID and session key values obtained via the login API endpoint. Each time admin authentication is used, the permissions of the user role are checked for validity for the particular endpoint.

The following HTTP headers must be passed to any API endpoint using admin authentication:

  • X-Spaaza-Session-User-Id: user ID of the user obtained via the login endpoint
  • X-Spaaza-Session-Key: session key of the session obtained via the login endpoint

Additionally, the following HTTP header is sometimes required:

  • X-Spaaza-MyPrice-App-Hostname: hostname of the Spaaza app the user wishes to apply the change to

Privileged Authentication​

Privileged authentication is available for certain trusted third-party systems using various API endpoints. Key exchange is used to supply the API consumer with the correct credentials, which are checked during each use of the endpoint.

The following HTTP authentication header is used to present the API with credentials:

  • Authorization: Bearer {access token ID}:{access token secret}

Additionally, the following HTTP header is sometimes required:

  • X-Spaaza-MyPrice-App-Hostname: {hostname of the Spaaza app the user wishes to apply the change to}