> For the complete documentation index, see [llms.txt](https://docs.mmoweb.biz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mmoweb.biz/rest-api/autentifikaciya.md).

# Аутентификация

### Обзор

API v2 использует Application Token (токены приложений) для аутентификации. Каждый токен предоставляет доступ к определённым endpoint'ам API с детальным контролем прав доступа.

**Ключевые характеристики:**

* Единовременная генерация: токены отображаются только один раз при создании
* Bearer токен: передаётся в заголовке `Authorization`
* Контроль доступа: каждый токен имеет специфические разрешения
* Привязка к проекту: каждый токен принадлежит одному проекту
* Отзываемость: токены можно отключить или удалить в любой момент
* Невосстанавливаемость: потерянный токен не может быть восстановлен; необходимо создать новый

***

### Создание Application Token

#### Где создать токен

Токены создаются и управляются в панели администратора.

{% hint style="info" %}
Создайте ваш первый [Application Token](https://mmoweb.biz/panel/settings/Globals.ApiKeyApp/add)
{% endhint %}

#### Процесс создания

1. Перейдите по ссылке выше
2. Укажите описательное имя для токена (для справки)
3. Настройте **"Доступы ключа"**, выбрав необходимые endpoint'ы API v2
4. Нажмите "Создать" или "Сохранить"
5. **Важно:** Скопируйте Application Token сразу — он больше не будет отображён

<figure><img src="/files/7Z46UiLizADTqlCOLnQ6" alt="" width="563"><figcaption></figcaption></figure>

#### Свойства токена

| Свойство       | Описание                                                     |
| -------------- | ------------------------------------------------------------ |
| Формат         | 64-символьная буквенно-цифровая строка                       |
| Отображение    | Показывается один раз при создании; больше не доступен       |
| Восстановление | Восстановление невозможно; требуется создание нового токена  |
| Управление     | Отключение, удаление, перевыпуск через панель администратора |

***

### Настройка прав доступа токена

#### Типы разрешений

Разрешения определяют, какие endpoint'ы API v2 может использовать токен.

В разделе **"Доступы ключа"**:

* Отметьте каждый endpoint, который разрешён для использования
* Неотмеченные endpoint'ы вернут ошибку `ACCESS_DENIED`
* Изменения вступают в силу немедленно

<figure><img src="/files/bRN6LOvHMDWsHyAEh8lY" alt="" width="512"><figcaption></figcaption></figure>

#### Область действия разрешений

**Application Token используется только для API v2.**

Не используйте Application Token для других версий API или сервисов.

***

### Использование токена

#### Заголовок Authorization

Все запросы к API v2 должны содержать токен в заголовке `Authorization`:

```http
Authorization: Bearer <токен>
```

#### Правила валидации токена

Токен должен:

* Содержать ровно 64 символа
* Существовать в системе
* Иметь статус "активен" (не отключён)
* Иметь хотя бы одно разрешение
* Быть привязанным к активному проекту

***

### Примеры аутентификации

#### cURL

```bash
curl -X GET "https://api.mmoweb.biz/v2/endpoint" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

#### JavaScript (fetch)

```javascript
const token = 'APPLICATION_TOKEN_HERE';

fetch('https://api.mmoweb.biz/v2/endpoint', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

#### PHP

```php
<?php

$token = 'APPLICATION_TOKEN_HERE';

$ch = curl_init('https://api.mmoweb.biz/v2/endpoint');

curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT);
?>
```

***

### Ошибки аутентификации и авторизации

#### Отсутствует заголовок Authorization

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "EMPTY_TOKEN"
}
```

**Причина:** Заголовок `Authorization` отсутствует в запросе.

**Решение:** Добавьте заголовок `Authorization: Bearer APPLICATION_TOKEN_HERE` в запрос.

***

#### Неверный формат токена

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "INVALID_TOKEN"
}
```

**Причина:** Токен должен содержать ровно 64 символа. Проверяется длина токена после удаления префикса `Bearer` .

**Решение:**

* Убедитесь, что вы скопировали полный токен
* Проверьте, что нет лишних пробелов в начале или конце
* При необходимости создайте новый токен в панели

***

#### Токен не существует в системе

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "TOKEN_NOT_FOUND"
}
```

**Причина:** Указанный токен не найден в системе.

**Решение:**

* Проверьте, что используете правильный токен
* Убедитесь, что токен не был удалён в панели
* Если токен потерян, создайте новый (восстановление невозможно)

***

#### Токен отключён

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "TOKEN_DISABLED"
}
```

**Причина:** Токен существует, но отключён (статус неактивен).

**Решение:**

* Включите токен в панели настроек
* Или создайте новый активный токен

***

#### Разрешения не настроены для токена

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "EMPTY_ACCESS"
}
```

**Причина:** Для токена не установлено ни одного разрешения на endpoint'ы.

**Решение:** Настройте хотя бы одно разрешение в разделе "Доступы ключа" при редактировании токена.

***

#### Проект не найден или неактивен

**HTTP Status:** `404 Not Found`

```json
{
  "success": false,
  "code": "PROJECT_NOT_FOUND"
}
```

**Причина:** Проект, к которому привязан токен, не существует или отключён в системе.

**Решение:**

* Проверьте статус проекта в панели администратора
* Свяжитесь с поддержкой, если проект должен быть активным

***

#### Endpoint не найден

**HTTP Status:** `404 Not Found`

```json
{
  "success": false,
  "code": "NOT_FOUND"
}
```

**Причина:** Запрошенный endpoint не существует в API v2, или неверно указан метод запроса (GET/POST).

**Решение:**

* Проверьте URL endpoint'а в документации
* Убедитесь, что используете правильный HTTP-метод (GET или POST)
* Проверьте, что версия API правильна (`/v2/`)

***

#### Доступ запрещён (недостаточно разрешений)

**HTTP Status:** `403 Forbidden`

```json
{
  "success": false,
  "code": "ACCESS_DENIED"
}
```

**Причина:** Токен не имеет разрешения на доступ к этому endpoint'у.

**Решение:**

* Добавьте этот endpoint в разрешения токена в панели ("Доступы ключа")
* Используйте другой токен, у которого есть это разрешение
* Проверьте корректность URL и метода запроса

***

### Лучшие практики безопасности

**Храните токены безопасно:**

* Используйте переменные окружения или защищённые системы управления конфигурацией
* Никогда не коммитьте токены в систему контроля версий (Git)
* Не передавайте токены в URL параметрах или логах

**Ограничивайте права токена:**

* Включайте только те endpoint'ы, которые действительно нужны
* Принцип наименьших привилегий снижает риск при компрометации токена

**Регулярно ротируйте токены:**

* Установите график замены токенов
* Создавайте новый токен перед удалением старого (без прерывания сервиса)

**Мониторьте использование:**

* Проверяйте логи на признаки подозрительной активности
* Отключайте токены, которые больше не используются

**Потеря токена:**

* Потерянный токен не может быть восстановлен
* Немедленно создайте новый и отключите скомпрометированный
* Обновите конфигурацию в вашем приложении

***

### Решение проблем

| Проблема          | Возможная причина                   | Решение                                         |
| ----------------- | ----------------------------------- | ----------------------------------------------- |
| `INVALID_TOKEN`   | Неправильная длина токена           | Проверьте, что токен содержит ровно 64 символа  |
| `TOKEN_NOT_FOUND` | Токен не существует                 | Проверьте значение; создайте новый если потерян |
| `TOKEN_DISABLED`  | Токен отключён                      | Включите токен в настройках или создайте новый  |
| `ACCESS_DENIED`   | Недостаточно разрешений             | Добавьте endpoint в разрешения токена           |
| `EMPTY_ACCESS`    | Разрешения не настроены             | Настройте "Доступы ключа" для токена            |
| `EMPTY_TOKEN`     | Отсутствует заголовок Authorization | Добавьте `Authorization: Bearer <токен>`        |