top of page
  • AutorenbildThomas Schiefer

Shopware 6 - How to use Store API to Register and Login a User

Aktualisiert: 16. Juli

This article will explain how you can use Swagger to explore the Shopware Store API and then successfully register new customers and log them into their new accounts.

Screenshot of Shopware Store API showing version and URL.
Shopware Store API

Table of Content:

How to get Swagger working

How do I get the sw-access key?

Summary of necessary steps to use Swagger

Register a Customer and Login with Swagger



Double opt-in workflow and differences to normal registration

Prerequisites: First, get your local environment up and running. Most likely this will be some sort of Docker setup. Check that your local environment is running by going to http://localhost. It will show your demo store or any other store.

A browsertab showing a basic Shopware demo-store.
Demostore on localhost

How to get Swagger working

Go to Swagger - browse to http://localhost/store-api/_info/swagger.html#/. You will see a page similar to this one:

The Swagger view for Shopware Store API.
Swagger for Shopware Store API

Try to execute a simple GET request - like the GET/sitemap request (spoiler alert: it will not work) by doing the following:

Press the “Try it out” button:

The GET/sitemap endpoint in Swagger

Then execute the request by pressing the “Execute” button:

The button for executing the GET/sitemap request.
Execute GET/sitemap

The response will be a 401 Unauthorized error:

A 401 error - unauthorized returned by GET/sitemap.
401 error - unauthorized

The error message tells us that we need to pass a "sw-access-key" to be allowed to access this API.

Scroll to the top of the page and press the "Authorize" button.

How to enter the sw-access-key in Swagger to be able to access the Shopware Store API.
Authorization with sw-access-key

How do I get the sw-access key?

Log in to your administration at http://localhost/admin#/login (default user and password are: admin/shopware. However, you may have already set up another admin account) and copy the sw-access-key from the corresponding sales channel (the one you want to query via the API).

The sw-access-key in the Shopware administration in the sales channel.
sw-access-key in the administration

Now execute the GET/sitemap request again. The response will be more useful now. We receive a response code 200 and the path to the sitemap:

A 200 success response - returned from GET/sitemap.
200 success - returned from GET/sitemap

If we want, we can download the sitemap with the returned path. It will look something like this:

An XML describing the Shopware sitemap for demo store.
Shopware sitemap for demo store

Congratulations, you are now able to successfully use the Swagger Store API in your local environment.

Summary of necessary steps to use Swagger

  1. Start local environment

  2. Browse to Swagger http://localhost/store-api/_info/swagger.html

  3. Get API token from administration http://localhost/admin

  4. Authorize Swagger against the according sales channel

  5. Use Swagger

Register a Customer and Login with Swagger

The GET/sitemap request was not very exciting, but it got us started. Let's do something more fun. Create a user and log in the new user.

Prerequisite: Go to your "Administration → Settings → Login & Sign-up" and make sure the Double opt-in on sign-up is disabled for your sales channel:

How to activate/deactivate the Double opt-in for registration workflow.
Double opt-in for registration workflow


We will start with this workflow because it is simpler. Later we will cover the workflow when double opt-in is enabled. Ok - now that we have double opt-in disabled, let's take a look at the POST/account/register request body.

A POST/account/register endpoint in Swagger.
POST/account/register endpoint

We can see that it is very long. It can take a lot of information. But we are going to try it with a simple request. So just copy and paste the following request body into your Swagger and hit the "Run" button (spoiler alert: the request will fail)

You will receive a 400 bad request error with the following details:

A 400 error - bad request because of a invalid salutationID returned from POST/account/register
400 error - bad request - invalid salutationID

The good thing about this error message is that it tells us exactly what the problem is. The value for salutationId does not exist in your system. But why do we need this salutationID at all, and why can we not pass a string like "Mr." to Shopware?

Because this is what we want to do with this request. We want to create a new customer. Mr. Thomas Schiefer (<salutation> <firstname> <lastname>). There are two reasons for this:

  1. Shopware is a multilingual system. So what language of salutation should we provide? Mr (English), Herr (German), Senor (Spanish), ...

  2. What if we change the salutation values in the future? The calling system would have to know which values are allowed.

So we just reference the according salutation by providing the salutationId. It becomes clearer when you look at the table for salutations directly:

The customer table in the Shopware database.
Customer table

You can see that the entries for Mr (English) and Herr (German) have the same salutationId, and other information such as the letter_name, which is used for greetings in emails, is also stored in this data structure.

So how do you get the correct value for salutationId when you call the POST/account/register endpoint? You could look in your local database, of course. But for calling systems in production, this is not an option. The easiest way to get all the salutation options is to go to http://localhost/store-api/salutation in your browser (spoiler alert: you will get an exception).

If you call http://localhost/store-api/salutation in your browser, you will get the following exception:

A 401 error - unauthorized - because of a missing sw-access-key in the request header.
401 error - unauthorized

We already know this exception from Swagger, the sw-access-key is missing, but how to pass the sw-access-key in the request header?

For Google Chrome we can install the ModHeader extension. This extension allows us to modify the request header and pass additional parameters like the sw-access-key:

Howto set sw-access-key in ModHeader.
Set sw-access-key in ModHeader

Once we put the sw-access-key parameter in ModHeader, we get a valid response containing all the salutations with their corresponding salutationIds from Shopware. Take the salutationId (in the response it is only called "id") and copy it to your request body in POST/account/register.

JSON response body for salutations from Shopware.

You need to repeat this step to get the countryId.

Just go to http://localhost/store-api/country to get a list of countries and their ids.

Now execute the POST/account/register request and you will receive a code 200 success response body similar to this one:

A successfull customer registration by calling POST/account/register.
Successful registration

To make sure our customer now exists in Shopware, we can do the following:

1. Open the administration and browse to customers:

The customer overview in the Shopware administration.
Customer overview

2. Try to login at the storefront with the new customers credentials:

The menu für logging in to Shopware.
Shopware Login

3. Check the database table customer for a new entry:

A new customer in the customer table in the Shopware database.
Customer table


Let's log in to Shopware using the POST/account/login endpoint. Open it in Swagger and modify the request body accordingly - with the user and password you set when you registered.

The POST/account/login endpoint in Swagger.

Then press the “Execute” button. You will receive a code 200 success message containing your contextToken:

The response body for a successful login to Shopware using the POST/account/login endpoint.
Successfully logged in

Double opt-in workflow and differences to normal registration

Legal requirements often make it necessary to enforce a double opt-in workflow when a customer registers an account. To enable this feature in Shopware we go to "Settings → Log-in & sign-up" and toggle the according switch to on:

Double opt-in activated in the Shopware administration.
Double opt-in activated

For each customer registration, Shopware now sends an email to the customer with a link that the customer must click to verify their account. Now when you register a customer using POST/account/register, Shopware will send the following email:

A double opt-in email shown in the Shopware log.
Double opt-in email

We can get the information about the sent mail in the logs. Go to "Settings → Logs" and check for mail.sent:

Shopware log messages showing a mail.sent message.
Shopware log messages

When analyzing the mail in more detail, we see the registration URL and its parameters:

A double opt-in URL containing parameters.
Double opt-in URL

The parameters are:

  • em=3fa51853488cbb4626ed15e325debc2bb83056bd

  • hash=3f9b5956408b493ca5c723c59bee003a

When looking at the Shopware Store API we see the following endpoint - POST/account/register-confirm - which takes those parameters.

The POST/account/register-confirm endpoint in Swagger.

When an external system needs to call this endpoint, it needs the values for hash and em. Where do we get these values from?

As developers, we can look at the customer database table:

The customer table in Shopware showing an entry with a hash set.
Customer table entry with hash

We see a column "hash" where for one row the hash value is filled in. This was a registration done with double opt-in = true. For the other customer registrations where we did not have double opt-in enabled, Shopware did not create a hash value.

As an external system, we cannot easily check the database. We see the POST/account/registration endpoint return the hash field, but unfortunately, it is empty. I guess this is for security reasons. If the hash were returned, it would be easy to create an account for a customer and immediately verify the account, making the double opt-in process kind of useless.

A response body with an empty hash returned for a successful registration.
Empty hash returned for registration

So how do we get the hash value? The response body contains the customer's unique id:

A customer ID in the response body, returned from POST/account/register.
Customer ID in the response body

We can use this id to query the Admin API search Endpoint: POST/api/search/customer

The easiest way to query that endpoint is using Postman. A working Postman Collection and how to use it is provided and explained in the next blog post.

For now, just take the value for hash from the database. So we know the hash value but are still missing the em value. Actually, the em value is not stored in the database but calculated on the fly with a SHA1 algorithm.

We know this because we can take a look at the Shopware source code: RegisterConfirmRoute.php Line 78

Code showing the em validation in RegisterConfirmRoute.php.
em validation in RegisterConfirmRoute.php

We see that em is calculated from the customer's email address using a SHA1 algorithm. How did we find this piece of code?

Just hit search in your project and look for the /account/register-confirm endpoint, because that is also the name of the route:

PHPStorm search for a Symfony route.
Search for route

The search also looks through the Shopware source because we have included the Shopware source in our project:

The path to the local Shopware source, included as library to PHPStorm.
Path to local libray

Shopware source is added as external library to the project.
External Library for Shopware source

Now that we know that em is calculated from the customer’s email with SHA1, let’s calculate it on

An online SHA1 generator showing the hash of an email address.
SHA1 generator

Finally, we can execute the POST/account/register-confirm endpoint:

A call to POST/account/register-confirm with values set in Swagger.
POST/account/register-confirm with values set

We get a 200 success code returned. And we can also check the customer table in the database, we now have a double_opt_in_confirm_date set for our customer:

Customer table with confirm date for double opt-in
Customer table with confirm date for double opt-in

In this blog article, we have covered how to register a customer through the Shopware Store API and log in to the customer. We have learned how to retrieve information such as salutations and country information. If you have any questions or comments, please feel free to contact us.

For how to use Postman to work with the Shopware Storefront API, keep continue reading the next blog post.

1.071 Ansichten1 Kommentar

Aktuelle Beiträge

Alle ansehen
bottom of page