# API overview

> Developer API keys, base endpoint, authentication, scopes, and rate limits.

MMW Cloud provides a REST API interface for automating file management and inspecting workspace storage quota.

## Base endpoint and authentication

Base API endpoint:

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

Every API call must include an Authorization header with a valid personal API key:

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

All API responses include an `X-Request-ID` header for distributed tracing and diagnostic review.

## Developer API keys

Programmatic access requires a personal API key:

- Key creation: visit the Profile view at https://app.mmwcloud.tech, navigate to the API Keys section, supply a label, choose required permissions, and define an expiration schedule.
- Key format: `mmwc_<prefix>_<secret>`. The prefix contains 16 hexadecimal characters, followed by a 43-character secret token.
- Secret security: the full key string is displayed exactly once upon initial creation. The backend database stores only an SHA-256 hash of the secret portion. Lost keys cannot be retrieved and must be reissued.
- Key capacity: accounts support up to 10 active keys concurrently. Revoked or expired keys do not count against this cap.
- Revocation: any active key can be revoked immediately using the Revoke action in the Profile view.

## Access scopes

Permissions are assigned per key and control allowable operations:

| Scope | Permitted actions |
| :--- | :--- |
| `files:read` | List files, inspect file metadata, request temporary download URLs, view storage quota. |
| `files:write` | Request upload tickets and submit upload completion confirmations. |
| `files:delete` | Soft-delete files from storage. |
| `quota:read` | Inspect current storage usage metrics and total quota limits. |

## Rate limiting

To ensure platform reliability, metadata endpoints enforce rate limits:

- Rate ceiling: 120 requests per minute per API key.
- Throttling response: requests exceeding the allowance return HTTP 429 with error code `rate_limit_exceeded`.
- `Retry-After` header: indicates the waiting interval in seconds before new requests are accepted.
- Rate telemetry headers: throttled responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`.