Hexclave REST API v1

完整的 REST API 参考文档 — 适用于任意语言/框架的前后端调用

概述

Hexclave 提供 REST API，支持前端（浏览器/移动端）和后端的任意编程语言调用。所有请求头以 X-Hexclave-* 为规范前缀，同时向后兼容 X-Stack-*（Hexclave 原名 Stack Auth）。

响应头 X-Hexclave-actual-status、X-Hexclave-known-error、X-Hexclave-request-id 会随对应的 X-Stack-* 等效头一同返回。

Base URL

认证方式

Client 端认证（浏览器 / 移动端）

curl https://authapi.cloudyun.top/ \
     -H "X-Hexclave-Access-Type: client" \
     -H "X-Hexclave-Project-Id: <项目 UUID>" \
     -H "X-Hexclave-Publishable-Client-Key: pck_<密钥>" \
     -H "X-Hexclave-Access-Token: <用户 access token>"

Publishable Client Key (pck_...) 可以安全地放在前端代码中。

Server 端认证（后端）

curl https://authapi.cloudyun.top/ \
     -H "X-Hexclave-Access-Type: server" \
     -H "X-Hexclave-Project-Id: <项目 UUID>" \
     -H "X-Hexclave-Secret-Server-Key: ssk_<密钥>"

Secret Server Key (ssk_...) 拥有全部用户数据的完全访问权限。

Admin 端认证

如需自行构建管理面板或通过代码修改项目配置，可使用 admin 访问类型配合 X-Hexclave-Super-Secret-Admin-Key。这些端点权限极高，请谨慎使用。

认证请求头一览

Header	类型	适用	说明
X-Hexclave-Access-Type	client | server | admin	全部必填	访问类型
X-Hexclave-Project-Id	UUID	全部必填	项目唯一标识
X-Hexclave-Publishable-Client-Key	string	Client必填	客户端密钥，以 pck_ 开头，可公开
X-Hexclave-Secret-Server-Key	string	Server必填	服务端密钥，以 ssk_ 开头，严禁公开
X-Hexclave-Super-Secret-Admin-Key	string	Admin可选	管理员超级密钥
X-Hexclave-Access-Token	string	Client可选	当前用户的访问令牌，用于以该用户身份操作
X-Hexclave-Refresh-Token	string	Client可选	刷新令牌，用于获取新的 access token
X-Hexclave-Branch-Id	UUID	全部可选	分支标识

API 端点

响应 — 200

Content-Type: text/plain

Welcome to the Hexclave API endpoint! Please refer to the
documentation at https://docs.hexclave.com/

Authentication: None

响应 — 200

{
  "access_token":  "eyJ...",
  "refresh_token": "eyJ...",
  "user_id":       "<user-id>"
}

响应 — 200

{
  "results": [
    { "user_id": "<user-id>" }
  ]
}

更多端点

以下为 Hexclave REST API 的其他可用端点分类。完整文档请参见 docs.hexclave.com。

分类	示例端点	访问类型
认证	POST /auth/anonymous/sign-up · POST /password/sign-in-with-email-and-password · POST /password/sign-up-with-email-and-password	Client
OTP / MFA	POST /otp/send-sign-in-code · POST /otp/sign-in-with-a-code · POST /otp/mfa-sign-in	Client
OAuth	GET /oauth/authorize · POST /oauth/token · GET /oauth/providers	Client
会话	GET /sessions · POST /sessions/refresh · DELETE /sessions/{id}	Client
团队 (Teams)	POST /teams · GET /teams/{id} · DELETE /teams/{id} · GET /teams/{id}/members	Client / Server
API 密钥	POST /api-keys · GET /api-keys · PATCH /api-keys/{id}	Client / Server
邮件	POST /emails/send-email · GET /emails/outbox · GET /emails/delivery-info	Server
权限 (RBAC)	GET /permissions · GET /teams/{id}/permissions	Client / Server
联系人渠道	POST /contact-channels · GET /contact-channels · POST /contact-channels/verify	Client / Server
关联账户	GET /connected-accounts	Client / Server
CLI 认证	POST /cli-auth/initiate · GET /cli-auth/poll · POST /cli-auth/complete	Client
密码管理	POST /password/send-reset-code · POST /password/reset · PATCH /password/update	Client
数据保险库	POST /data-vault/store · GET /data-vault/retrieve	Server
支付	POST /payments/purchase-session · GET /payments/item	Client / Server

错误处理

Hexclave API 返回标准 HTTP 状态码，错误响应附带 JSON body 含详细信息。

状态码	含义	说明
400	Bad Request	请求参数无效
401	Unauthorized	认证无效或缺失
403	Forbidden	权限不足
404	Not Found	资源不存在
429	Too Many Requests	超出速率限制，响应头中会注明重试时间
500	Internal Server Error	服务器错误

FAQ

支持哪些编程语言？

任何可以发送 HTTP 请求的语言都可以使用 Hexclave REST API，包括 JavaScript、Python、Ruby、Java、Go、C#、Dart 等。

Client 和 Server 访问类型有什么区别？

Client（X-Hexclave-Access-Type: client）用于浏览器/移动端，只能读写当前登录用户的数据，使用 pck_... 密钥。
Server（X-Hexclave-Access-Type: server）用于安全后端，拥有全部用户数据的完全访问权限，使用 ssk_... 密钥。绝不要将 Server 密钥暴露在客户端。

Admin 访问类型是什么？

如果需要自行构建 Hexclave 管理面板或通过代码修改项目配置，可以使用 admin 类型。这些端点权限极高，请谨慎使用。

有速率限制吗？

是的。速率限制因端点和访问类型而异。超出限制时会返回 429 Too Many Requests，响应头中包含重试时间。