Authentication

Introduction

Spaaza supports three different authentication methods, with one sub-method. 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. User authentication uses HTTP headers containing user ID and session key values obtained from the login API endpoint. The following headers must be passed to any API endpoint using user authentication:

X-Spaaza-Session-User-Id: user ID of the user obtained from the login endpoint
X-Spaaza-Session-Key: session key of the session obtained from 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.

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 from 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 from the login endpoint
X-Spaaza-Session-Key: session key of the session obtained from 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}