凭证与密钥

模型凭证、SSH 公钥、API Token。 完整参数、请求 / 响应 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

模型凭证、SSH 公钥、API Token。

凭证与密钥 Operations

• get/model-providers
• post/credentials
• get/credentials
• delete/credentials/{name}
• post/ssh-keys
• get/ssh-keys
• delete/ssh-keys/{name}
• post/tokens
• get/tokens
• delete/tokens/{id}

内置模型厂商目录（中国市场五家 + 自定义兼容端点）

​Copy link

Auth Required

Copy as Markdown

Responses

• 200

  目录全量（常量表，不分页；三种角色一律可见）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/model-providers

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 目录全量（常量表，不分页；三种角色一律可见）Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "providers": [
    {
      "id": "deepseek",
      "display_name": "DeepSeek（深度求索）",
      "credential_name": "ANTHROPIC_AUTH_TOKEN",
      "native_credential_names": [
        "DEEPSEEK_API_KEY"
      ],
      "base_url_env": "ANTHROPIC_BASE_URL",
      "model_env": "ANTHROPIC_MODEL",
      "base_url": "string",
      "models": [
        {
          "id": "deepseek-flash[1m]",
          "display_name": "DeepSeek Flash（1M 上下文）",
          "extra_config": {
            "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-flash[1m]"
          }
        }
      ],
      "default_model": "string",
      "base_url_hint": "string"
    }
  ]
}

JSONCopy

JSONCopy

目录全量（常量表，不分页；三种角色一律可见）

存凭证（同名 upsert 覆盖 = 密钥轮换）

​Copy link

Auth Required

Copy as Markdown

Headers

• Idempotency-Key

  Type: string

  max length:  

  128Copy link to Idempotency-Key

  幂等键；≤ 128 字符；命中则原样重放缓存响应

Body·CredentialCreate

required

application/json

• name

  Type: string

  max length:  

  64

  required

  Copy link to name

  凭证名（组织内唯一的身份，可自取，如 kimi-prod）。 多条模型连接并存靠的就是各自不同的名字。≤ 64 字符，无正则校验（以实现为准）。 注入时用的环境变量名不是它，而是槽位 —— 见 CredentialListItem.slot

• secret

  Type: string

  max length:  

  8192

  required

  Copy link to secret

  凭证本体；永不回显、不进审计响应

• config

  Type: objectCopy link to config

  非密参数：扁平 env 覆盖表，如 {"ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic", "ANTHROPIC_MODEL": "kimi-k2.5"}。 键必须 ⊆ 创建沙箱时该 agent 镜像该凭证名的 [[credentials]].config_env， 否则创建沙箱 400（details.field = credentials）—— 这是 D9「不静默失败」的延伸。 键名由厂商目录的 base_url_env / model_env 给出，前端不得硬编码

  Properties: 1
• provider

  Type: stringCopy link to provider

  厂商 id，取值见 GET /v1/model-providers；省略或空串 = 无厂商 归属的纯密钥（如 GITHUB_TOKEN）。取值域外 → 400

Responses

• 201

  已创建（或同名覆盖）

  application/json
• 400

  name 为空或超 64 字符；provider 不在 GET /v1/model-providers 的取值域； config 语法非法（非 object、键非环境变量名、值为空或含控制字符、 超 512 字节、键数超 8）；secret 为空或超 8 KiB。 失败时 details.field ∈ {name, provider, config, secret}

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/credentials

Shell Curl

curl https://api.rayrunos.com/v1/credentials \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "provider": "",
  "config": {
    "additionalProperty": ""
  },
  "secret": ""
}'

cURLCopy

cURLCopy

Status: 201 已创建（或同名覆盖）Status: 400 name 为空或超 64 字符；provider 不在 GET /v1/model-providers 的取值域； config 语法非法（非 object、键非环境变量名、值为空或含控制字符、 超 512 字节、键数超 8）；secret 为空或超 8 KiB。 失败时 details.field ∈ {name, provider, config, secret} Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "name": "string",
  "provider": "string"
}

JSONCopy

JSONCopy

已创建（或同名覆盖）

列出凭证元数据与注入规则

​Copy link

Auth Required

Copy as Markdown

Responses

• 200

  全量（不分页）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误（含镜像目录不可读 —— 注入规则读不到时整体失败， 不返回一个把「不知道」说成「没人用」的列表）

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/credentials

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 全量（不分页）Status: 401 未认证Status: 500 内部错误（含镜像目录不可读 —— 注入规则读不到时整体失败， 不返回一个把「不知道」说成「没人用」的列表）Status: 503 依赖不可用

Show Schema

{
  "credentials": [
    {
      "name": "string",
      "provider": "string",
      "slot": "string",
      "secret_mask": "sk-ant-a…wxyz",
      "config": {
        "additionalProperty": "string"
      },
      "injection_rules": [
        {
          "agent": "claude-code",
          "version": "1",
          "method": "env",
          "path": "string"
        }
      ],
      "created_at": "2026-11-11T06:00:17.727Z",
      "updated_at": "2026-11-11T06:00:17.727Z"
    }
  ]
}

JSONCopy

JSONCopy

全量（不分页）

删除凭证（严格 404：删除后无痕迹，无幂等 204）

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• name

  Type: string

  max length:  

  64

  required

  Copy link to name

  凭证名（同 POST 的 name 约束：非空、≤ 64；实现不做正则校验）

Responses

• 204

  Copy link to 204

  已删除

• 401

  未认证

  application/json
• 404

  凭证不存在（not_found， 严格语义）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for delete/credentials/{name}

Shell Curl

curl 'https://api.rayrunos.com/v1/credentials/{name}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已删除Status: 401 未认证Status: 404 凭证不存在（not_found， 严格语义）Status: 500 内部错误Status: 503 依赖不可用

No Body

已删除

注册 / 轮换 SSH 公钥（同名 upsert 覆盖）

​Copy link

Auth Required

Copy as Markdown

Headers

• Idempotency-Key

  Type: string

  max length:  

  128Copy link to Idempotency-Key

  幂等键；≤ 128 字符；命中则原样重放缓存响应

Body·SSHKeyUpsert

required

application/json

• name

  Type: string

  max length:  

  64

  required

  Copy link to name

  公钥名（本组织内唯一）。 创建沙箱时通过 sandbox.ssh_keys[] 引用。

• public_key

  Type: string

  max length:  

  8192

  required

  Copy link to public_key

  一行 OpenSSH authorized_keys 格式公钥（公钥不是秘密，但仍属 用户资源 —— 全局审计 api.request 已覆盖，载荷本身不写入 journal， 纪律 1）。解析失败的细节由 400 details.field=public_key 给出。

Responses

• 201

  已注册（或同名覆盖轮换）；响应仅含 name + fingerprint

  application/json
• 400

  name 为空或超 64 字符；public_key 不是合法 OpenSSH authorized_keys 行（ssh.ParseAuthorizedKey 拒绝）或超 8 KiB。 失败时 details.field ∈ {name, public_key}

  application/json
• 401

  未认证

  application/json
• 409

  组织内 SSH 公钥数量已达上限（8 条）。 失败码 = resource_exhausted

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/ssh-keys

Shell Curl

curl https://api.rayrunos.com/v1/ssh-keys \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "public_key": ""
}'

cURLCopy

cURLCopy

Status: 201 已注册（或同名覆盖轮换）；响应仅含 name + fingerprintStatus: 400 name 为空或超 64 字符；public_key 不是合法 OpenSSH authorized_keys 行（`ssh.ParseAuthorizedKey` 拒绝）或超 8 KiB。 失败时 details.field ∈ {name, public_key} Status: 401 未认证Status: 409 组织内 SSH 公钥数量已达上限（8 条）。 失败码 = resource_exhausted Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "name": "string",
  "fingerprint": "string"
}

JSONCopy

JSONCopy

已注册（或同名覆盖轮换）；响应仅含 name + fingerprint

列出本组织 SSH 公钥元数据

​Copy link

Auth Required

Copy as Markdown

Responses

• 200

  全量（不分页）；按 name 升序

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/ssh-keys

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 全量（不分页）；按 name 升序Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "ssh_keys": [
    {
      "name": "string",
      "fingerprint": "string",
      "created_at": "2026-11-11T06:00:17.727Z"
    }
  ]
}

JSONCopy

JSONCopy

全量（不分页）；按 name 升序

删除 SSH 公钥

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• name

  Type: string

  max length:  

  64

  required

  Copy link to name

  公钥名（同 POST 的 name 约束：非空、≤ 64）

Responses

• 204

  Copy link to 204

  已删除

• 401

  未认证

  application/json
• 404

  name 在本组织不存在（not_found， 严格语义）—— 含「同名 但属于别的组织」也走 not_found，不泄露存在性

  application/json
• 409

  被沙箱引用时拒绝删除（K38 —— 拒绝删除是廉价的，权限复活是 昂贵的）。响应码 = in_use，in_use_by 字段告诉用户该去 哪些沙箱里清理。引用计数 = 本组织内创建时 ssh_keys 列表里 包含该 name 的去重沙箱数（按 journal_entries 投影）。

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for delete/ssh-keys/{name}

Shell Curl

curl 'https://api.rayrunos.com/v1/ssh-keys/{name}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已删除Status: 401 未认证Status: 404 name 在本组织不存在（not_found， 严格语义）—— 含「同名 但属于别的组织」也走 not_found，**不泄露存在性** Status: 409 被沙箱引用时拒绝删除（K38 —— 拒绝删除是廉价的，权限复活是 昂贵的）。响应码 = `in_use`，**in_use_by** 字段告诉用户该去 哪些沙箱里清理。引用计数 = 本组织内创建时 ssh_keys 列表里 包含该 name 的去重沙箱数（按 journal_entries 投影）。 Status: 500 内部错误Status: 503 依赖不可用

No Body

已删除

创建 API token（明文仅在创建响应出现一次）

​Copy link

Auth Required

Copy as Markdown

Body·TokenCreate

required

application/json

• name

  Type: string

  min length:  

  1

  max length:  

  128

  required

  Copy link to name
• expires_at

  Type: string | nullFormat: date-timeCopy link to expires_at

  可选；缺省 = 永不过期

• source

  Type: "web" or "cli"enumCopy link to source

  创建来源标记，缺省 web。cli 表示由命令行登录创建，网页会话 不能撤销该类 token（需在命令行执行 rayrun logout）。这是来源 标记，不是权限控制。

Responses

• 201

  token 已创建（★ token 明文仅此一次）

  application/json
• 400

  name 为空或超 128 字符（invalid_request）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for post/tokens

Shell Curl

curl https://api.rayrunos.com/v1/tokens \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "expires_at": null,
  "source": "web"
}'

cURLCopy

cURLCopy

Status: 201 token 已创建（★ token 明文仅此一次）Status: 400 name 为空或超 128 字符（invalid_request）Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "token": "string",
  "token_id": "string",
  "name": "string",
  "source": "web",
  "created_at": "2026-11-11T06:00:17.727Z",
  "expires_at": null
}

JSONCopy

JSONCopy

token 已创建（★ token 明文仅此一次）

列出 token 元数据

​Copy link

Auth Required

Copy as Markdown

Responses

• 200

  token 列表（无 secret）

  application/json
• 401

  未认证

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/tokens

Shell Curl

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

cURLCopy

cURLCopy

Status: 200 token 列表（无 secret）Status: 401 未认证Status: 500 内部错误Status: 503 依赖不可用

Show Schema

{
  "tokens": [
    {
      "token_id": "string",
      "name": "string",
      "source": "web",
      "created_at": "2026-11-11T06:00:17.727Z",
      "expires_at": null,
      "last_used_at": null
    }
  ]
}

JSONCopy

JSONCopy

token 列表（无 secret）

撤销 token（立即生效，Redis 即真相源；严格 404）

​Copy link

Auth Required

Copy as Markdown

Path Parameters

• id

  Type: string

  required

  Copy link to id

  token_id

Responses

• 204

  Copy link to 204

  已撤销

• 401

  未认证

  application/json
• 403

  token 由命令行创建（source=cli），浏览器会话不能撤销；请在同一台 机器执行 rayrun logout，或使用 Bearer Token 撤销。

  application/json
• 404

  token 不存在（not_found， 严格语义）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for delete/tokens/{id}

Shell Curl

curl 'https://api.rayrunos.com/v1/tokens/{id}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已撤销Status: 401 未认证Status: 403 token 由命令行创建（source=cli），浏览器会话不能撤销；请在同一台 机器执行 `rayrun logout`，或使用 Bearer Token 撤销。 Status: 404 token 不存在（not_found， 严格语义）Status: 500 内部错误Status: 503 依赖不可用

No Body

已撤销

Models

Show More