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. Admin login requires Two-Factor Authentication (2FA) on every API version: the login response contains a session passcode key, a passcode is emailed to the admin user, and the session is obtained by passing both to the session endpoint. Admin users marked as login_2fa_exempt receive the session directly from the login response. 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}

Acting on behalf of an end-user​

A small number of endpoints allow a privileged client to act on behalf of a specific end-user by adding the following header to a request made with privileged authentication:

  • X-Spaaza-On-Behalf-Of: {Spaaza user ID of the end-user}

The request is then processed as if it had been made by that end-user, so the user_id parameter is not needed. The header is currently supported by lock-voucher and delete-voucher only.

The access token must be scoped to the chain to which the end-user belongs. If the end-user belongs to a different chain, or cannot be matched to a chain, the request is rejected with the error access_denied (code 424). The value of the header must be a numeric Spaaza user ID; any other value is rejected with the error no_valid_user (code 267).

Sending the X-Spaaza-On-Behalf-Of header to an endpoint that does not support it is rejected with the error access_denied (code 424). Previously such a request was processed as an ordinary privileged request, with the header ignored. API clients should only send the header to the endpoints listed above.

Access token revocation​

Each request made with privileged authentication checks that the credentials are still valid. The request is rejected with the error access_token_invalid (code 266, HTTP status 401) if any of the following is true:

  • the access token ID or the access token secret is not correct
  • the access token is inactive or has been deleted
  • the service client that owns the access token is disabled or has been deleted

An access token can be revoked by setting its active property to false or by deleting it. All access tokens of a service client can be revoked at once by setting the service client's enabled property to false or by deleting the service client. See the AccessToken and ServiceClient resources for details.

A revocation made through the Resources API can take up to one hour to take effect. Contact Spaaza if an access token must be revoked immediately.

Requests made with a revoked access token, or with an access token of a disabled or deleted service client, previously returned the error access_denied (code 424). They now return access_token_invalid (code 266). API clients that check for access_denied in this situation should check for access_token_invalid instead.