Platform · API

API 中心

集中申请与管理你的 API 凭证与 OAuth 应用：一套凭证 = API 标识（apiId）+ API 密钥（apiKey），调用登录类 API（MC 服务器登录 / 通用登录）时携带配套的 apiId + apiKey 即可；外部开发者可注册 OAuth 应用（授权码 / 设备码流程），在用户细粒度授权后接入生态。凭证兑换与应用管理在 开发者控制台，接入文档请前往 文档中心 查阅。

认证方式
所有登录请求在 Header 携带 X-Api-Id 与 X-Api-Key，二者配套使用。
PIN / 密码字段须先用服务端公钥加密为密文，明文不直接传输。
存量旧密钥可额外携带 X-Server-Key 头走兼容模式。
速率限制
每日额度按 UTC 零点重置，默认 100 次 / 日（以授权码为准）。
触发 429 后当日不可继续调用，次日零点自动恢复。
兑换、停用、删除等敏感操作均需人机验证，一次性有效。
向下滚动
01
开发者控制台
凭证管理与 OAuth 应用管理已独立为控制台页
进入控制台
凭证管理：兑换授权码生成 API 凭证（apiId + apiKey 一套），停用 / 删除 / 作废管理与本页原有一致。
OAuth 应用：注册外部接入应用，从细粒度权限总表中勾选并标记「必要 / 可选」，管理回调地址与密钥；提交后由审核员人工审核，通过后才能发起授权。
敏感操作策略不变：人机验证一次性有效，危险操作需验证标签页登录态。
OAuth 2.0 与设备码（外部开发者接入）
授权码模式（Web 应用）：引导用户到 /oauth/ 授权页，用户细粒度勾选同意后回调你的 redirect_uri 换取令牌。
设备码模式（启动器 / CLI）：POST /api/oauth/device 发起，用户在授权页输入设备码确认，轮询 /api/oauth/token 获取令牌。
细粒度权限：用户名 / ID / 头像 / 签名 / 等级与皮肤站角色、材质逐项独立授权；必要权限锁定、可选权限由用户勾选。
获取令牌后调用 /api/oauth/userinfo 与 /api/oauth/characters，仅返回用户同意的权限范围数据。皮肤站原有 Yggdrasil 协议端点不受影响。
02
三步拿到凭证
提工单 → 审核发码 → 控制台兑换
01

提交申请工单

前往 工单中心 提交「API 接入申请」或「API 密钥申请」工单，说明使用场景，两类工单的授权码均可在开发者控制台兑换。

02

审核发放授权码

审核员审核通过后，会在工单回复中发放一次性授权码（有效期以工单说明为准），请妥善保管、切勿外传。

03

兑换生成凭证

在开发者控制台填入授权码即可兑换生成一套凭证：API 标识（apiId）+ API 密钥（apiKey），凭证用途由审核员发放授权码时指定。每日额度由授权码决定（接入申请默认 100），将其配置到你的服务器 / 系统中即可。

03
端点与请求示例
登录 API 端点一览与完整请求报文
端点一览
POST/api/auth/loginMC 服务器登录
POST/api/auth/universal通用登录
GET/api/auth/refresh会话刷新
POST/api/auth/logout登出
请求示例
POST /api/auth/login HTTP/1.1
X-Api-Id: ak_live_••••
X-Api-Key: 你的密钥
Content-Type: application/json

{ "uuid": "…", "pin": "加密字段" }
04
状态码图例
按颜色速览响应含义
2xx
成功，凭证有效并计入额度
4xx
请求有误，检查参数 / 凭证
401/403
未登录或权限不足
429
当日额度耗尽，UTC 零点重置
5xx
服务端异常，稍后重试
05
常见错误码
排查请求失败时先对照此表
错误码速查
状态码含义
400请求参数缺失或格式错误（UUID / PIN / 公钥格式不符）
401未登录或登录态失效，需重新登录后再调用
403apiId / apiKey 不匹配或已被停用
429当日额度耗尽，等待 UTC 零点重置
500服务端内部错误，稍后重试或提工单反馈
登录 API 完整接入文档（协议 / 请求响应 / 错误码）：文档中心 → API 文档