API reference user management - WEBSALE Dokumentation

The user management API reference describes endpoints for managing user accounts and individual settings in the admin interface of the shop. The interface can be used to create, edit, and delete users, as well as retrieve and update personal settings such as language or dashboard configuration. Access to the respective endpoints depends on the permissions of the logged-in user.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	PUT	POST	DELETE
User account in admin area	admin/user
User settings	admin/settings

General

Data fields of a user account

Name	Type	Usage
id	Integer	Unique ID of the user
firstName	String	First name of the user
lastName	String	Last name of the user
role	Array	Roles within the company as an array, for example [“marketing”, “seo”]
email	String	Email address of the user
userName	String	User name of the user
permissions	Object	Permissions of the user for services

Example

{
    "email": "vx-shop@websale.de",
    "firstName": "Horst",
    "id": 1,
    "lastName": "Schlämmer",
    "userName": "vx-shop",
    "permissions": {
        "admin": {
            "0": true
        }
    },
    "role": ["productMaintainer"]
}

Data fields of user settings

Name	Type	Usage
dashboard.content[]	Array	List of configured widgets on the user dashboard
dashboard.content[].position.cols	Integer	Number of columns the widget occupies
dashboard.content[].position.rows	Integer	Number of rows the widget occupies
dashboard.content[].position.x	Integer	Horizontal position of the widget in the grid
dashboard.content[].position.y	Integer	Vertical position of the widget in the grid
dashboard.content[].settings	Object	Individual settings for the respective widget
dashboard.content[].settings.shortcuts[]	Array	(Only for the “shortcuts” widget) List of link shortcuts
dashboard.content[].settings.shortcuts[].label	String	Text displayed on the button
dashboard.content[].settings.shortcuts[].route	String	Internal route opened on click
dashboard.content[].widgetId	String	Unique identifier of the widget used
firstName	String	First name of the user
language	String	Language code of the user (for example “deu”)
lastName	String	Last name of the user
salutation	String	Salutation of the user (`m`, `w`, or `d`)
colorScheme	String	Color scheme of the admin interface

Example

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 3,
                    "rows": 4,
                    "x": 0,
                    "y": 0
                },
                "settings": {},
                "widgetId": "salesTrend"
            },
            {
                "position": {
                    "cols": 3,
                    "rows": 2,
                    "x": 0,
                    "y": 4
                },
                "settings": {},
                "widgetId": "inbox"
            },
            {
                "position": {
                    "cols": 2,
                    "rows": 3,
                    "x": 3,
                    "y": 0
                },
                "settings": {},
                "widgetId": "conversion-rate-trends"
            },
            {
                "position": {
                    "cols": 2,
                    "rows": 5,
                    "x": 3,
                    "y": 3
                },
                "settings": {
                    "shortcuts": [
                        {
                            "label": "Zu Kategorien",
                            "route": "/categories"
                        },
                        {
                            "label": "Zu Produkten",
                            "route": "/products"
                        },
                        {
                            "label": "Zu Bestellungen",
                            "route": "/orders"
                        }
                    ]
                },
                "widgetId": "shortcuts"
            }
        ]
    },
    "firstName": "Horst",
    "language": "deu",
    "lastName": "Schlämmer",
    "salutation": "m",
    "colorScheme": "light"
}

Permissions

Technical name	Meaning	Values
`"admin"`	Full access to all areas	`0 = Active`
`"products"`	Products	`0 = Read` `1 = Write` `2 = Create` `3 = Delete` `4 = WriteProtectedFields`
`"productvariants"`	Product variants	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"productRatings"`	Product reviews	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"inventory"`	Product stock	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"productFields"`	Product fields	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"categories"`	Categories	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"categoryFields"`	Category fields	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"configuration"`	Configurations	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"seo"`	SEO	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"sitemaps"`	Sitemaps	`0 = Read` `1 = Create` `2 = Write` `3 = Delete` `4 = Publish`
`"datafeeds"`	Data feeds	`0 = Read` `1 = Write` `2 = Create` `3 = Delete` `4 = Publish`
`"orders"`	Orders	`0 = Read` `1 = Write` `2 = Delete`
`"inquiries"`	Inquiries	`0 = Read` `1 = Write` `2 = Delete`
`"texts"`	Text blocks	`0 = Read` `1 = Write` `2 = Create` `3 = Delete` `4 = Publish`
`"templates"`	Shop page templates	`0 = Read` `4 = Publish`
`"customerAccounts"`	Customer data	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"vouchers"`	Vouchers	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"transactions"`	Transactions	`0 = Read` `1 = Write`
`"keyValue"`	Key-value store	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"newsletter"`	Newsletter	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"blacklist"`	Newsletter blacklist	`0 = Add` `1 = Remove`
`"statistics"`	All statistics	`0 = Read`
`"logs"`	Logs	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"strapi"`	Link to the Strapi CMS	`0 = Read`
`"dashboard"`	Dashboard in the AI	`0 = Read`
`"imageconverter"`	Image converter	`0 = Read` `1 = Write` `2 = Create` `3 = Delete` `4 = Publish`
`"paypalonboarding"`	PayPal onboarding	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`
`"paymentprovider"`	Payment provider	`0 = Read` `1 = Write` `2 = Create` `3 = Delete`

Permissions example

"permissions": {
    "admin": {
        "0": false
    },
    "newsletter": {
        "0": true,
        "1": true,
        "2": true,
        "3": true
    },
    "customerAccounts": {
        "0": true,
        "1": false,
        "2": false,
        "3": false
    },
    "products": {
        "0": true,
        "1": false,
        "2": false,
        "3": false,
        "4": false
    }
}

The user does not have full access (the admin.0 (admin.active) permission is set to false). However, they can use the entire newsletter service, because the permissions newsletter.0 (newsletter.Read), newsletter.1 (newsletter.Write), newsletter.2 (newsletter.Create), and newsletter.3 (newsletter.Delete) are set to true. In addition, they can read customer and product data, because the permissions customerAccounts.0 (customerAccounts.Read) and products.0 (products.Read) are set to true.

Methods for user accounts

The /admin/user endpoint enables the management of user accounts. Through it, users can be created, modified, deleted, and retrieved.

GET admin/user

This endpoint returns a list of all user accounts from the admin interface of the shop.

Example

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

Response

{
    "endReached": true,
    "items": [
        {
            "id": 1,
            "role": [],
            "firstName": "",
            "lastName": "",
            "email": "",
            "permissions": {...}
        },
        ...
    ],
    "nextPageToken": "NA",
    "totalCount": 5
}

Filter fields

id, firstName, lastName, email, privileges, websale

Sort fields

id, firstName, lastName, email, websale

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read users.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET admin/user/self

This endpoint loads the data of the currently logged-in user account.

Example

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

Response

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "id": 1,
    "lastName": "Mustermann",
    "userName": "m.mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
404 Not Found		The account was not found in the database.

GET admin/user/{accountId}

This endpoint loads the data of a specific user account by accountId.

Example

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

Response

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "id": 1,
    "lastName": "Mustermann",
    "userName": "m.mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read users.
400 Bad Request	”invalidFormat”	`accountId` is invalid.
400 Bad Request	”invalidValue”	`accountId` is 0.
404 Not Found		The account was not found in the database.

GET admin/permissions

This endpoint returns a list of all permissions a user can have.

Example

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

Response

{
    "items": [
        {
            "id": "strapi",
            "permissions": [
                {
                    "id": 0,
                    "name": "read"
                }
            ]
        },
        {
            "id": "logs",
            "permissions": [
                {
                    "id": 0,
                    "name": "read"
                },
                {
                    "id": 1,
                    "name": "write"
                },
                {
                    "id": 2,
                    "name": "create"
                },
                {
                    "id": 3,
                    "name": "delete"
                }
            ]
        },
        {
            "id": "blacklist",
            "permissions": [
                {
                    "id": 0,
                    "name": "write"
                },
                {
                    "id": 1,
                    "name": "delete"
                }
            ]
        },
        ...
    ]
}

POST admin/user

This endpoint creates a new user account for the admin interface. When creating, either a password can be set directly or an email with a password setup link can be sent.

Example

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

Request body

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "lastName": "Mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"],
    "passwordEmail": true
}

Response

{
    "id": 42,
    "role": ["marketing"],
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "m.mustermann@websale.de",
    "permissions": {...}
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`firstName`, `lastName`, `email`, or `password` are not strings. `passwordEmail` is not a boolean. `role` is not an array. `permissions` is not a JSON object.
400 Bad Request	”missing”	`email` or `permissions` is missing. `password` is missing (if `passwordEmail` is not set to `true`).
400 Bad Request	”invalidCombination”	A password is specified although `passwordEmail` is set to `true`.
400 Bad Request	”unknownDataField”	An unknown field was sent.
503 Service Unavailable	”internalError”	Email could not be sent.

POST admin/passwordChange

This endpoint changes the password of the currently logged-in user account. The new password must not match the previous password. After a successful change, the shop ends all other sessions of the account. The session you use to make the change remains active.

Example

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

Request body

{
    "newPassword": <new password>,
    "newPasswordAgain": <new password>,
    "oldPassword": <old password>
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`newPassword`, `newPasswordAgain`, or `oldPassword` is missing.
400 Bad Request	”invalidValue”	`newPassword` and `newPasswordAgain` do not match. `newPassword` is shorter than 12 characters or too weak. `oldPassword` does not match the account password. `newPassword`, `newPasswordAgain`, or `oldPassword` are empty strings.
400 Bad Request	”invalidFormat”	`newPassword`, `newPasswordAgain`, or `oldPassword` are not strings.
400 Bad Request	”unknownDataField”	An unknown field was sent.
401 Unauthorized		Not authorized: you do not have the required write permissions.
403 Forbidden		The account is locked.
409 Conflict		`newPassword` is identical to the previous password.

POST admin/resend/{accountId}

This endpoint sends an email with a password reset link to the email address associated with the user account.

Example

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

Request body

{}

Response

{
    "id": 9,
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have administrator permissions.
400 Bad Request	”invalidFormat”	`accountId` is not an integer.
400 Bad Request	”invalidValue”	`accountId` is 0.
404 Not Found		The account was not found.
503 Service Unavailable	”internalError”	The email could not be sent.

PUT admin/user/{accountId}

This endpoint updates the information of a user account by accountId.

Example

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

Request body

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "lastName": "Mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Response

{
    "id": 42,
    "role": ["marketing"],
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "m.mustermann@websale.de",
    "permissions": {...}
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`accountId` is invalid. `firstName`, `lastName`, or `email` are not strings. `role` is not an array. `permissions` is not a JSON object.
400 Bad Request	”unknownDataField”	An unknown field was sent.
404 Not Found		The account was not found.

DELETE admin/user/{accountId}

This endpoint deletes an existing user account by accountId.

Example

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

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions. An account owned by Websale AG must not be deleted.
400 Bad Request	”invalidFormat”	`accountId` is invalid.
400 Bad Request	”invalidValue”	`accountId` is 0.
404 Not Found		The account was not found.

Methods for user settings

The /admin/settings endpoint enables the saving and retrieving of user-related settings.

GET admin/settings

This endpoint loads the current settings of the currently logged-in user, such as language, name, and dashboard configuration.

Example

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

Response

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 2,
                    "rows": 2,
                    "x": 0,
                    "y": 0
                },
                "settings": {
                    "timeBetweenReloads": -1
                },
                "widgetId": "salesToday"
            }
        ]
    },
    "colorScheme": "light",
    "firstName": "Max",
    "language": "deu",
    "lastName": "Mustermann",
    "salutation": "m"
}

Error codes

Error	Type	Reason
404 Not Found		There are no saved settings for the active account.

PUT admin/settings

This endpoint updates the user settings. Parameters not provided retain their previous value.

Example

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

Request body

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 2,
                    "rows": 2,
                    "x": 0,
                    "y": 0
                },
                "settings": {
                    "timeBetweenReloads": -1
                },
                "widgetId": "salesToday"
            }
        ]
    },
    "colorScheme": "light",
    "firstName": "Max",
    "language": "deu",
    "lastName": "Mustermann",
    "salutation": "m"
}

Response

<Settings as JSON, same as with GET>

Error codes

Error	Type	Reason
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`dashboard.content`, `dashboard.content.widgetId`, `dashboard.content.position`, `dashboard.content.position.cols`, `dashboard.content.position.rows`, `dashboard.content.position.x`, or `dashboard.content.position.y` is missing.
400 Bad Request	”unknownDataField”	An unknown field was sent.
400 Bad Request	”invalidFormat”	`dashboard` is not a JSON object. `salutation`, `language`, `colorScheme`, `firstName`, or `lastName` are not strings.
400 Bad Request	”invalidValue”	`salutation` is not a valid value (allowed: `m`, `w`, `d`).
401 Unauthorized		Not authorized: you do not have the required write permissions.
404 Not Found		There are no saved settings for the active account.
503 Service Unavailable	”internalError”	Saving failed.

Support

For technical questions and assistance, our support team is available to you: To the customer portal Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​General

​Data fields of a user account

​Example

​Data fields of user settings

​Example

​Permissions

​Permissions example

​Methods for user accounts

​GET admin/user

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET admin/user/self

​Example

​Response

​Error codes

​GET admin/user/{accountId}

​Example

​Response

​Error codes

​GET admin/permissions

​Example

​Response

​POST admin/user

​Example

​Request body

​Response

​Error codes

​POST admin/passwordChange

​Example

​Request body

​Response

​Error codes

​POST admin/resend/{accountId}

​Example

​Request body

​Response

​Error codes

​PUT admin/user/{accountId}

​Example

​Request body

​Response

​Error codes

​DELETE admin/user/{accountId}

​Example

​Response

​Error codes

​Methods for user settings

​GET admin/settings

​Example

​Response

​Error codes

​PUT admin/settings

​Example

​Request body

​Response

​Error codes

​Support

Supported methods

General

Data fields of a user account

Example

Data fields of user settings

Example

Permissions

Permissions example

Methods for user accounts

GET admin/user

Example

Response

Filter fields

Sort fields

Error codes

GET admin/user/self

Example

Response

Error codes

GET admin/user/{accountId}

Example

Response

Error codes

GET admin/permissions

Example

Response

POST admin/user

Example

Request body

Response

Error codes

POST admin/passwordChange

Example

Request body

Response

Error codes

POST admin/resend/{accountId}

Example

Request body

Response

Error codes

PUT admin/user/{accountId}

Example

Request body

Response

Error codes

DELETE admin/user/{accountId}

Example

Response

Error codes

Methods for user settings

GET admin/settings

Example

Response

Error codes

PUT admin/settings

Example

Request body

Response

Error codes

Support