> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference authentication

> Sign in to the WEBSALE Admin Interface API with shop user credentials, obtain access tokens, and learn how role-based permissions gate endpoints.

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/        | <br /><Icon icon="check" /> | <br /><Icon icon="check" /> | <br /><Icon icon="ban" /> | <br /><Icon icon="ban" /> |

## 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](/en/schnittstellen/admin-interface-api/api-referenz-benutzerverwaltung).

## 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login/checkToken/<token>
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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.                                                       |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "grantType": "apiKey",
    "apiKey": <api key>
}
```

or

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "grantType": "password",
    "user": <username>,
    "password": <password>
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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. |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login/refresh
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "refreshToken": <refreshToken>
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true,
    "accessToken": <accessToken>
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                                |
| ---------------- | ------------------ | ------------------------------------------------------------------------- |
| 400 Bad Request  |                    | Request body could not be loaded. <br /> 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.                     |

### POST login/passwordLink

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

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login/passwordLink
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "email": "m.mustermann@websale.de"
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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.          |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login/setPassword
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "password_new": <new password>,
    "password_new_again": <new password>,
    "otok": <double opt-in token>
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**       | **Type**           | **Reason**                                                                                                                                                                     |
| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 Bad Request |                    | Request body could not be loaded. <br /> The `double opt-in token` is invalid or does not allow the password to be changed. <br /> 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.<br />The password is shorter than 12 characters.<br />`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.                                                                                                                                                     |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/login/logout
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

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