# Обзор API

> Персональные ключи API, базовый адрес, авторизация, права доступа и лимиты запросов.

MMW Cloud предоставляет интерфейс REST API для автоматизации управления файлами и мониторинга квоты хранилища.

## Базовый адрес и авторизация

Базовый адрес API:

```text
https://api.mmwcloud.tech/v1
```

Каждый запрос к API должен содержать заголовок авторизации с действующим персональным ключом:

```http
Authorization: Bearer mmwc_<prefix>_<secret>
```

Ответы API сопровождаются диагностическим заголовком `X-Request-ID` для отслеживания запросов в журналах.

## Ключи API разработчика

Для программного доступа используются персональные ключи:

- Создание ключа: откройте вкладку «Профиль» в кабинете https://app.mmwcloud.tech, найдите блок «Ключи API», введите имя ключа, выберите необходимые права доступа и задайте срок действия.
- Формат ключа: `mmwc_<prefix>_<secret>`. Префикс состоит из 16 шестнадцатеричных символов, секретная часть содержит 43 символа.
- Безопасность секрета: полное значение ключа показывается только один раз сразу после генерации. На сервере сохраняется исключительно хеш SHA-256 от секрета. При утере секретной части ключ необходимо отозвать и создать новый.
- Лимит ключей: на одном аккаунте допускается до 10 действующих ключей одновременно. Истекшие по сроку и отозванные ключи не учитываются в этом лимите.
- Отзыв ключа: отозвать ключ можно в любой момент кнопкой «Отозвать» в списке ключей профиля.

## Права доступа (scopes)

При генерации ключа задается набор разрешенных операций:

| Право | Разрешенные действия |
| :--- | :--- |
| `files:read` | Просмотр списка файлов, чтение метаданных, получение ссылки на скачивание, чтение квоты. |
| `files:write` | Запрос тикета на загрузку файла и подтверждение завершения загрузки. |
| `files:delete` | Мягкое удаление файлов из хранилища. |
| `quota:read` | Просмотр текущего объема использованного дискового пространства и общего лимита квоты. |

## Ограничение частоты вызовов (Rate Limits)

Для защиты инфраструктуры к эндпоинтам метаданных применяется ограничение:

- Лимит: 120 запросов в минуту на каждый ключ API.
- Превышение лимита: сервер возвращает статус HTTP 429 с кодом ошибки `rate_limit_exceeded`.
- Заголовок `Retry-After`: указывает количество секунд, через которое можно повторить запрос.
- Информационные заголовки: ответы содержат заголовки `RateLimit-Limit`, `RateLimit-Remaining` и `RateLimit-Reset`.