认证与账号

登录 / 登出 / 注册 / 邀请接受 / 改密 / 当前身份。 完整参数、请求 / 响应 schema 见下方（本页只渲染该组）：

Open SearchSearchKeyboard Shortcut:Control⌃ k

v0.1.0

OpenAPI 3.0.3

Rayrun API

Download OpenAPI Document

json

Download OpenAPI Document

yaml

Rayrun REST API —— 控制台与命令行（rayrun CLI）的统一接口，也是自托管部署的 第三方集成的接入点。共 13 组、93 个端点（分组见左侧栏或「介绍」页的接口一览）。 基地址与部署同源：<实例地址>/v1（如 https://rayrun.example.com/v1）。 认证：Bearer Token（控制台「设置 → 我的 API Token」或 rayrun login 创建） 或浏览器会话 Cookie；GET /health 免认证。详见「介绍」页的认证一节。

Server

Server:https://api.rayrunos.com/v1

Rayrun 托管平台

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

认证与账号

​Copy link

登录 / 登出 / 注册 / 邀请接受 / 改密 / 当前身份。

认证与账号 Operations

• post/auth/login
• post/auth/logout
• get/auth/me
• post/auth/register
• post/auth/accept-invite
• post/auth/password

密码登录（豁免幂等）

​Copy link

Copy as Markdown

Body·LoginRequest

required

application/json

• password

  Type: string

  min length:  

  1

  required

  Copy link to password

  空串 → 400 invalid_request

• username

  Type: string

  min length:  

  1

  max length:  

  255

  required

  Copy link to username

  用户名或邮箱（统一走此字段，兼容既有客户端）。空串 → 400 invalid_request。含 @ 时按邮箱校验与查询（邮箱不存在 → 401， 与密码错误不可区分）；否则按用户名查询。两者均去首尾空白并转小写比较。

Responses

• 200

  登录成功，设置 rayrun_session cookie（HttpOnly; SameSite=Strict; Path=/；HTTPS 时加 Secure）。不返回 302

  application/json
• 400

  username/password 空串，或 username 字段以 @ 形式提交但邮箱格式不合法（invalid_request）

  application/json
• 401

  凭据错误（invalid_credentials —— 用户名或邮箱、密码不匹配）

  application/json
• 403

  密码登录全局未启用（login_disabled：RAYRUN_ADMIN_PASSWORD 未设置且 users 表为空，fail-closed）

  application/json
• 429

  登录失败限流（too_many_attempts，带 retry_after_seconds）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

  application/json

Request Example for post/auth/login

Shell Curl

curl https://api.rayrunos.com/v1/auth/login \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "",
  "password": ""
}'

cURLCopy

cURLCopy

Status: 200 登录成功，设置 rayrun_session cookie（HttpOnly; SameSite=Strict; Path=/；HTTPS 时加 Secure）。不返回 302Status: 400 username/password 空串，或 username 字段以 @ 形式提交但邮箱格式不合法（invalid_request）Status: 401 凭据错误（invalid_credentials —— 用户名或邮箱、密码不匹配）Status: 403 密码登录全局未启用（login_disabled：RAYRUN_ADMIN_PASSWORD 未设置且 users 表为空，fail-closed）Status: 429 登录失败限流（too_many_attempts，带 retry_after_seconds）Status: 500 内部错误Status: 503 依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

Show Schema

{
  "tenant_id": "string",
  "user_id": "string",
  "username": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "role": "owner",
  "email_binding_required": true,
  "platform_admin": true
}

JSONCopy

JSONCopy

登录成功，设置 rayrun_session cookie（HttpOnly; SameSite=Strict; Path=/；HTTPS 时加 Secure）。不返回 302

登出

​Copy link

Auth Required

Copy as Markdown

Responses

• 204

  已登出

• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

  application/json

Request Example for post/auth/logout

Shell Curl

curl https://api.rayrunos.com/v1/auth/logout \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已登出Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

No Body

已登出

当前身份

​Copy link

Auth Required

Copy as Markdown

Responses

• 200

  当前用户信息

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

  application/json

Request Example for get/auth/me

Shell Curl

curl https://api.rayrunos.com/v1/auth/me \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 当前用户信息Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用（service_unavailable —— 依赖故障与 401 严格区分）

Show Schema

{
  "tenant_id": "string",
  "user_id": "string",
  "username": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "role": "owner",
  "email_binding_required": true,
  "platform_admin": true
}

JSONCopy

JSONCopy

当前用户信息

自助注册（免认证 + 按 IP 注册限流；注册即建组织，注册者 = 该组织所有者）

​Copy link

Copy as Markdown

豁免幂等（请求体含明文密码）。成功后注册即登录： 201 + Set-Cookie（与 login 同款属性）。组织名 = username，不可改。

注册赠金：新组织同时入账一笔赠金，金额 = env RAYRUN_SIGNUP_GRANT_CENTS（默认 5000 = ¥50；0 = 不发）。落为一条 billing.credit，payload.source.type = "grant"、ref_id = tenant_id。 账户上体现为余额 +5000 分。接受邀请（/auth/accept-invite）与平台 代开组织不发 —— 赠金对标的是「自助注册」，不是「组织被创建」。

Body·RegisterRequest

required

application/json

• email

  Type: string

  max length:  

  255

  required

  Copy link to email

  必填；去首尾空白并转小写后存储，全局唯一（大小写不敏感）。不做邮箱验证。格式非法或已被占用分别返回 400 / 409（details.field = "email"）

• password

  Type: string

  min length:  

  8

  required

  Copy link to password

  至少 8 位（自助注册规则；登录不设下限 —— 存量账号可能更短）

• username

  Type: string

  min length:  

  1

  max length:  

  64

  required

  Copy link to username

  非空；规范化后仅允许 [a-z0-9._-] 且不超过 64 字符；非保留名（RAYRUN_ADMIN_USERNAME 与 slug 落在 default/anonymous/system 的均拒绝）。比较大小写不敏感：服务端规范化为小写后存储与比对，Admin / ADMIN 与 admin 视为同一名字。同时作为组织标识，注册后不可修改

• display_name

  Type: string

  max length:  

  255Copy link to display_name

  可选；≤255 字符（users.display_name VARCHAR(255)，超限 400 invalid_request）

Responses

• 201

  注册成功，设置 rayrun_session cookie（注册即登录）

  application/json
• 400

  email/username/password 缺失或空串、email 格式不合法、username 为保留名/不符合规范化白名单 [a-z0-9._-]/超过 64 字符、password 少于 8 位（invalid_request；username 规范化后比对）

  application/json
• 403

  注册未开放（registration_disabled：RAYRUN_REGISTRATION_OPEN 关闭）

  application/json
• 409

  username 或 email 已被占用（name_conflict；details.field = username / email）

  application/json
• 429

  注册限流（too_many_attempts，按 IP 计数，计每次尝试、成功不清零，带 retry_after_seconds）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/auth/register

Shell Curl

curl https://api.rayrunos.com/v1/auth/register \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "",
  "username": "",
  "password": "",
  "display_name": ""
}'

cURLCopy

cURLCopy

Status: 201 注册成功，设置 rayrun_session cookie（注册即登录）Status: 400 email/username/password 缺失或空串、email 格式不合法、username 为保留名/不符合规范化白名单 [a-z0-9._-]/超过 64 字符、password 少于 8 位（invalid_request；username 规范化后比对）Status: 403 注册未开放（registration_disabled：RAYRUN_REGISTRATION_OPEN 关闭）Status: 409 username 或 email 已被占用（name_conflict；details.field = username / email）Status: 429 注册限流（too_many_attempts，按 IP 计数，计每次尝试、成功不清零，带 retry_after_seconds）Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "tenant_id": "string",
  "tenant_name": "string",
  "user": {
    "user_id": "string",
    "tenant_id": "string",
    "username": "string",
    "display_name": "string",
    "role": "owner",
    "disabled_at": null,
    "created_at": "2026-11-11T06:00:17.727Z"
  }
}

JSONCopy

JSONCopy

注册成功，设置 rayrun_session cookie（注册即登录）

接受邀请（免认证；一次性链接，token 明文只在邀请创建响应出现一次）

​Copy link

Copy as Markdown

按 token 哈希查未过期、未撤销、未接受的邀请；成功后建 user（角色由邀请指定）、 标记 accepted_at，接受即登录 → 201 + Set-Cookie。邀请先到先得、不预占 username。

Body·AcceptInviteRequest

required

application/json

• password

  Type: string

  min length:  

  1

  required

  Copy link to password
• token

  Type: string

  required

  Copy link to token

  邀请链接里的 token

• display_name

  Type: string

  max length:  

  255Copy link to display_name

  可选；≤255 字符（users.display_name VARCHAR(255)，超限 400 invalid_request）

Responses

• 201

  接受成功，设置 rayrun_session cookie（接受即登录）

  application/json
• 400

  token/password 空串，或 username 不符合规范化白名单 [a-z0-9._-]（invalid_request；规范化后比对）

  application/json
• 404

  邀请不存在 / 已过期 / 已撤销 / 已接受（not_found）

  application/json
• 409

  username 已被注册（name_conflict）

  application/json
• 429

  接受邀请限流（too_many_attempts，计每次尝试、成功不清零，带 retry_after_seconds）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/auth/accept-invite

Shell Curl

curl https://api.rayrunos.com/v1/auth/accept-invite \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "token": "",
  "password": "",
  "display_name": ""
}'

cURLCopy

cURLCopy

Status: 201 接受成功，设置 rayrun_session cookie（接受即登录）Status: 400 token/password 空串，或 username 不符合规范化白名单 [a-z0-9._-]（invalid_request；规范化后比对）Status: 404 邀请不存在 / 已过期 / 已撤销 / 已接受（not_found）Status: 409 username 已被注册（name_conflict）Status: 429 接受邀请限流（too_many_attempts，计每次尝试、成功不清零，带 retry_after_seconds）Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "tenant_id": "string",
  "user_id": "string",
  "username": "string",
  "email": "string",
  "display_name": "string",
  "avatar_url": "string",
  "role": "owner",
  "email_binding_required": true,
  "platform_admin": true
}

JSONCopy

JSONCopy

接受成功，设置 rayrun_session cookie（接受即登录）

修改自己的密码（已认证；需验旧密码；成功后清当前 session 键）

​Copy link

Auth Required

Copy as Markdown

Body·PasswordChange

required

application/json

• new_password

  Type: string

  min length:  

  1

  required

  Copy link to new_password
• old_password

  Type: string

  min length:  

  1Copy link to old_password

  password_set=1 时必填；微信自动建号（password_set=0）首次设置密码可省略。旧密码错误返回 400 invalid_request + details.field=old_password。

Responses

• 204

  Copy link to 204

  已修改

• 400

  字段缺失/空串，或旧密码错误（invalid_request；旧密码错带 details.field = "old_password" —— 不是 401，避免 web 全局跳登出；计入 rayrun:pwd:fail: 独立计数器，不复用登录的）

  application/json
• 401

  未认证（middleware 统一 401）

  application/json
• 429

  失败限流（too_many_attempts，按 rayrun:pwd:fail: 独立计数器，带 retry_after_seconds）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/auth/password

Shell Curl

curl https://api.rayrunos.com/v1/auth/password \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "old_password": "",
  "new_password": ""
}'

cURLCopy

cURLCopy

Status: 204 已修改Status: 400 字段缺失/空串，或旧密码错误（invalid_request；旧密码错带 details.field = "old_password" —— 不是 401，避免 web 全局跳登出；计入 rayrun:pwd:fail:<username> 独立计数器，不复用登录的）Status: 401 未认证（middleware 统一 401）Status: 429 失败限流（too_many_attempts，按 rayrun:pwd:fail:<username> 独立计数器，带 retry_after_seconds）Status: 500 内部错误Status: 503 依赖不可用

No Body

已修改

Models

Show More