Member authentication

To start a loyalty session, a client must authenticate a member using one of the authentication methods, which follow the OAuth 2.0 framework.

Loyalty session

A loyalty session represents an authenticated session exclusive to a particular member, authenticated through one of the supported authentication methods.

During a loyalty session, a client will be allowed to access various member-specific endpoints (that follow the /ocapi/v1/members/current route structure) and features on behalf of the authenticated loyalty member.

Authentication methods

OCAPI supports both token-based and cookie-based authentication for various use cases.

Token authentication

Token-based authentication is recommended for clients that can securely store the access token and refresh token locally. This method is appropriate for clients that don't run on a web browser and require granular control of member authentication.

Use the CreateAuthenticationToken endpoint to authenticate a member and create a JWT access token.

NOTE

When using token-based authentication, the access token must be manually refreshed when it expires. Use the refresh token to create a new access token as required.

Cookie authentication

Cookie-based authentication is recommended for web-based clients. It allows the Digital Platform and the web browser to automatically handle the majority of the logic involved to maintain the authentication session.

Use the CreateAuthenticationCookie endpoint to authenticate a member. This endpoint returns two cookies:

  • vista-loyalty-member-authentication-token - an HTTP-only cookie containing the access token and refresh token.
  • vista-loyalty-member-is-authenticated - a empty cookie that JavaScript clients can use to determine whether the patron is authenticated.

As the authentication cookie is HTTP-only, it can be expired by the API using the ExpireAuthenticationCookie endpoint.

NOTE

When using cookie-based authentication, the API will automatically refresh the cookie when the access token has expired.

Authentication credentials

The following credentials are supported by both cookie and token authentication methods:

Password

This credentials method uses standard loyalty member username/email and password credentials. The credential is requested as URL-encoded content in the request body. For example:

Copy
Copied
Content-Type: application/x-www-form-urlencoded
grant_type=password&username={username}&password={password}&club_id={clubId}
NOTE

An unknown password can be reset via the member password reset flow. A known password can also be updated via the member password update flow.

Refresh token

This credentials method allows for an existing loyalty session to be extended without a member needing to re-enter their credentials. The credential is requested as URL-encoded content in the request body. For example:

Copy
Copied
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refreshToken}

External issuer (i.e., social sign on)

In addition to using the credentials stored within Loyalty, OCAPI can authenticate with any external issuer provided the issuer is linked with a member in Loyalty.

External issuers are configured as a plugin system so options available will vary per environment. Use the GetMasterData endpoint to get the list of configured externalAuthenticationIssuers.

The credential is requested as URL-encoded content in the request body. For example:

Copy
Copied
Content-Type: application/x-www-form-urlencoded
grant_type=external_issuer&external_issuer_id={externalIssuerId}&external_token={externalToken}