Customer Login by Token overview

Edit on GitHub

Most modern e-commerce applications allow customers to log in by token or, in other words, they support token-based authentication. They do so for several good reasons:

  • Tokens are stateless: They are stored on the client side and already contain all the information they need for authentication. No session information on the server is great for scaling your application.

  • Tokens are secure: Tokens (not cookies) are sent on every request, which helps to prevent attacks. Since the session is not stored, there is no session-based information that could be manipulated.

  • Extensibility and access control: In the token payload, you can specify user roles, permissions as well as resources that the user can access. Besides, you can share some permissions with other applications.

Customer Login by Token feature allows B2B users to log in to Spryker Shop using a token.

A token is a unique identifier that contains all the information needed for authentication to fetch a specific resource without using a username and password. The tokens are JSON strings that are encoded in base64url format.

The lifetime of the token is 8 hours by default, but this value can be changed on the project level.

Token Structure

Every token consists of the three sections separated by periods.

Token struc

  • Header contains the information about the token type (JWT) and the encryption algorithm (RS256). For example:
  "typ": "JWT",
  "alg": "RS256",
  "jti": "9ced66ac5cefe17681576bf95b800078e3020142faaa524da871ffb2a63508952045e10453136bde"

Once the header is encoded, we get the part of the token:

  • Payload is the part where multiple claims (statements) about the user identity and additional data, for example, permissions are stored. Here we put the information that we need to transmit. id_customer and idcompanyuser are included by default, however, you can extend the payload with any data according to your project requirements.

Example payload:

     "aud": "frontend",
      "jti": "9ced66ac5cefe17681576bf95b800078e3020142faaa524da871ffb2a63508952045e10453136bde",
      "iat": 1557926620,
      "nbf": 1557926620,
      "exp": 1557955420,
      "sub": "    {\"customer_reference\":null,\"id_customer\":6,\"id_company_user\":\"1\",\"permissions\":null}",
  "scopes": []

The example above contains six registered claims that, when encoded, correspond to:

  • Signature contains the hash of the header, the payload and the secret needed

The example signature is the following:

  base64UrlEncode(header) + "." +

The final part of the encoded token will look like this:


Combining the three parts, an exemplary URL with the full token will look like:

In Spryker Commerce OS, token generation is performed using a facade method, that is why no GUI is present. To generate a token, see HowTo - Generate a Token for Login.

Token-based authentication works closely with the Punch Out feature. It allows B2B buyers to log in from their ERP system to a Spryker company user account using a token without entering the username and password and buy the products from Spryker e-commerce shop.

To make the feature more flexible, we have implemented the functionality that allows you to disable switching between the Business-on Behalf accounts. E.g., if the user logs in to the pre-defined company account that has Business-on-Behalf feature integrated, the shop owner can disable the ability to switch between the accounts. In case the Business-on-Behalf is disabled, the company user will log in to the default account and will not be able to switch between the company users within their company account.

Module Relations for Customer Login by Token feature are schematically represented in the following diagram:

Module relations

If you are: