API reference authentication

The authentication API reference describes how users can log in via the REST API. Login is performed with a user account that is managed in the admin interface of the shop.
After successful authentication, further REST API endpoints can be used — depending on assigned permissions — e.g. to process inquiries or manage orders.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	POST	PUT	DELETE
Authentication	login/

General

To access the REST API, you need a user account for the admin interface of the shop. The permissions and roles of this account control which REST API endpoints you may access and which HTTP methods (GET, POST, PUT, DELETE) are available to you. Example:

A user with only read permissions can retrieve inquiries but cannot edit or delete them.
A user with administrator permissions has full access to all REST services and methods.

If access to certain REST endpoints is denied, your user account is probably missing the corresponding permission. In this case, contact your responsible shop administrator. For more information about managing users and assigning permissions, see the section API reference user management.

Using the methods

This endpoint checks a double opt-in token (otok) for validity. It is used, for example, in the password reset process.

Example

https://www.<your-shop>.de/admin/api/v1/login/checkToken/<token>

Response

{
    "success": true,
    "id": <accountId from token>
}

Error codes

Error	Type	Reason
400 Bad Request	”missing”	`otok` is missing.
400 Bad Request	”invalidValue”	`otok` is invalid or already used, or does not allow the password to be changed.
404 Not Found		The account was not found.

This endpoint enables login via email/password or via an API key (apiKey). On successful authentication, an accessToken and a refreshToken are returned. If the ?setCookie parameter is specified in the URL, the tokens are set as cookies and the refreshToken is not returned in the JSON response.

Example

https://www.<your-shop>.de/admin/api/v1/login

Request body

{
    "grantType": "apiKey",
    "apiKey": <api key>
}

{
    "grantType": "password",
    "user": <username>,
    "password": <password>
}

Response

{
    "success": true,
    "accessToken": <accessToken>,
    "refreshToken": <refreshToken>
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded.
401 Unauthorized		The account has `id` 0.
403 Forbidden		The account is locked.
404 Not Found		The account could not be loaded.
503 Service Unavailable	”internalError”	Refresh token could not be created.

This endpoint issues a new accessToken, authorized via a valid refreshToken. If the ?setCookie parameter is specified in the URL, the endpoint additionally sets the new accessToken as a cookie.

Example

https://www.<your-shop>.de/admin/api/v1/login/refresh

Request body

{
    "refreshToken": <refreshToken>
}

Response

{
    "success": true,
    "accessToken": <accessToken>
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded. The token type is not “Refresh”.
400 Bad Request	”invalidFormat”	`refreshToken` has an invalid type (expected: string).
400 Bad Request	”unknownDataField”	An unknown field was sent.
401 Unauthorized		The token has expired.
403 Forbidden		The account is locked.
404 Not Found		The token or the corresponding account was not found.

This endpoint sends an email containing a password reset link to the specified email address.

Example

https://www.<your-shop>.de/admin/api/v1/login/passwordLink

Request body

{
    "email": "m.mustermann@websale.de"
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`email` is missing.
400 Bad Request	”invalidValue”	`email` is an empty string.
400 Bad Request	”invalidFormat”	`email` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was sent.
404 Not Found		The account was not found.
503 Service Unavailable	”internalError”	Email could not be sent.

This endpoint sets a new password for a user account. The action must be authorized by a valid double opt-in token that was previously sent by email (login/passwordLink).

Example

https://www.<your-shop>.de/admin/api/v1/login/setPassword

Request body

{
    "password_new": <new password>,
    "password_new_again": <new password>,
    "otok": <double opt-in token>
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded. The `double opt-in token` is invalid or does not allow the password to be changed. The password is too weak.
400 Bad Request	”missing”	`double opt-in token`, `password_new`, or `password_new_again` is missing.
400 Bad Request	”invalidValue”	`password_new` and `password_new_again` do not match. The password is shorter than 12 characters. `password_new`, `password_new_again`, or `otok` are empty strings.
400 Bad Request	”invalidFormat”	`password_new`, `password_new_again`, or `otok` are not strings.
400 Bad Request	”unknownDataField”	An unknown field was sent.
403 Forbidden		The account is locked.
404 Not Found		The account was not found.

This endpoint logs out the current user. The cookies set for accessToken and refreshToken are deleted and the refresh token is removed from the database.

Example

https://www.<your-shop>.de/admin/api/v1/login/logout

Request body

{}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

General

Using the methods

Example

Response

Error codes

Example

Request body

Response

Error codes

Example

Request body

Response

Error codes

Example

Request body

Response

Error codes

Example

Request body

Response

Error codes

Example

Request body

Response

Error codes

​Supported methods

​General

​Using the methods

​GET login/checkToken/{otok}

​Example

​Response

​Error codes

​POST login

​Example

​Request body

​Response

​Error codes

​POST login/refresh

​Example

​Request body

​Response

​Error codes

​POST login/passwordLink

​Example

​Request body

​Response

​Error codes

​POST login/setPassword

​Example

​Request body

​Response

​Error codes

​POST login/logout

​Example

​Request body

​Response

​Error codes

Supported methods

General

Using the methods

GET login/checkToken/{otok}

Example

Response

Error codes

POST login

Example

Request body

Response

Error codes

POST login/refresh

Example

Request body

Response

Error codes

POST login/passwordLink

Example

Request body

Response

Error codes

POST login/setPassword

Example

Request body

Response

Error codes

POST login/logout

Example

Request body

Response

Error codes