---
url: https://milthm.cn/wiki/en/manual/developer/milkloud.md
description: Start integrating with Milkloud authentication and APIs.
---

# Milkloud

Milkloud provides authentication and online data services for Milthm. Applications can use OpenID Connect (OIDC) to
act on behalf of multiple users. A user can instead create a User Token for a personal script or another trusted tool.

## API Base URLs

Choose the API base used by the Milkloud service that the user accesses.

| Service | API base                          |
|---------|-----------------------------------|
| China   | `https://milkloud.milthm.cn/api`  |
| Global  | `https://milkloud.milthm.com/api` |

Append the endpoint paths in this guide to the selected API base.

## Choose an Authentication Method

| Use case                                                  | Method                                       | Credential sent to the API             |
|-----------------------------------------------------------|----------------------------------------------|----------------------------------------|
| A website, native app, or service used by multiple people | [OIDC](https://milthm.cn/wiki/en/manual/developer/milkloud/authentication.md#openid-connect)   | `Authorization: Bearer <access_token>` |
| A personal script or trusted private tool                 | [User Token](https://milthm.cn/wiki/en/manual/developer/milkloud/authentication.md#user-token) | `Authorization: Basic <credential>`    |

Do not embed a User Token in a public website, distributed app, public repository, log, or support message. Use OIDC
when each user must grant access to an application.

## HTTP Conventions

| Parameter         | Location | Required | Default | Description                                                                                                                            |
|-------------------|----------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------|
| `Accept-Language` | Header   | No       | English | A standard language preference such as `ja, en;q=0.8`. It changes human-readable messages, not the response schema or symbolic `code`. |

Timestamps use RFC 3339 and may include a UTC offset and fractional seconds.

## Response Envelope

Milkloud API responses use a common JSON envelope:

```ts
export interface MilkloudResponse<T> {
    code: string;
    message: string;
    data?: T;
}
```

A successful response has `code` and `message` set to `OK`. Errors use a non-success HTTP status and a symbolic `code`.
See [Errors](https://milthm.cn/wiki/en/manual/developer/milkloud/errors.md) for recovery guidance.

## API Overview

See [Scopes](https://milthm.cn/wiki/en/manual/developer/milkloud/scopes.md) for each scope's capability, inclusion rules, and support by OIDC and User Tokens.

| Operation                                             | Method and path                 | Required resource scope                                   |
|-------------------------------------------------------|---------------------------------|-----------------------------------------------------------|
| Read a public profile                                 | `GET /v1/user/:identity`        | None                                                      |
| Read the current user's profile                       | `GET /v1/user`                  | Fields depend on `openid`, `profile`, `user`, and `email` |
| Update the current user's nickname                    | `PATCH /v1/user`                | `user`                                                    |
| Read cloud-save metadata                              | `GET /v1/game/save/info`        | `milthm:save:read`                                        |
| Request a cloud-save download URL                     | `GET /v1/game/save`             | `milthm:save:read`                                        |
| Read the current user's recent scores                 | `GET /v1/user/:username/recent` | `milthm:event:recent`                                     |
| Read the current user's Reality and best performances | `GET /v1/user/:username/rank`   | `milthm:stats:best_performance`                           |

See [Scopes](https://milthm.cn/wiki/en/manual/developer/milkloud/scopes.md), [Errors](https://milthm.cn/wiki/en/manual/developer/milkloud/errors.md), [Profile](https://milthm.cn/wiki/en/manual/developer/milkloud/profile.md), [Cloud Save](https://milthm.cn/wiki/en/manual/developer/milkloud/cloud-save.md), and
[Recent Scores and Rank](https://milthm.cn/wiki/en/manual/developer/milkloud/user-scores.md) for request and response details.