Skip to main content
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/infoEndpointsGETPOSTPUTDELETE
Authenticationlogin/



​
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

​
GET login/checkToken/{otok}

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

ErrorTypeReason
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 FoundThe account was not found.

​
POST login

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>
}
or 
{
    "grantType": "password",
    "user": <username>,
    "password": <password>
}

​
Response

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

​
Error codes

ErrorTypeReason
400 Bad RequestRequest body could not be loaded.
401 UnauthorizedThe account has id 0.
403 ForbiddenThe account is locked.
404 Not FoundThe account could not be loaded.
503 Service Unavailable”internalError”Refresh token could not be created.

​
POST login/refresh

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

ErrorTypeReason
400 Bad RequestRequest 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 UnauthorizedThe token has expired.
403 ForbiddenThe account is locked.
404 Not FoundThe token or the corresponding account was not found.

​
POST login/passwordLink

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

ErrorTypeReason
400 Bad RequestRequest 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 FoundThe account was not found.
503 Service Unavailable”internalError”Email could not be sent.

​
POST login/setPassword

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

ErrorTypeReason
400 Bad RequestRequest 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 ForbiddenThe account is locked.
404 Not FoundThe account was not found.

​
POST login/logout

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

ErrorTypeReason
400 Bad RequestRequest body could not be loaded.