接口文档

更新日期：2026-05-28 11:00:41

洋葱头openAPI接口文档

OpenAPI 是洋葱头浏览器的开放接口服务，允许第三方系统通过标准 HTTP API 访问团队的组织架构、密码库（Vault）、短信记录等数据。

快速开始

前置条件

你有 Onion 管理后台的团队管理员权限
在管理后台获取到一个 Secret（对应 openapi_key 表中的 secret 字段）

第一条 API 请求

curl -H "Authorization: Bearer <你的Secret>" \
  "https://<你的部署地址>/openapi/v2/team/department"

鉴权方式

所有 v2 接口统一使用 Bearer Token 方式鉴权。

方式	说明
位置	HTTP Header `Authorization`
格式	`Bearer <secret>`
示例	`Authorization: Bearer xxxxxx`
说明	secret 由管理员在 Onion 管理后台生成，对应数据库 `openapi_key` 表的 secret 字段

注意：v2 接口无需签名计算，也无需先换 Token。只需在每次请求时携带 Authorization Header 即可。

通用响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

字段	类型	说明
`code`	int	业务状态码，0 表示成功，非 0 表示错误
`message`	string	提示信息（成功时为空或 "success"）
`data`	object/array	业务数据

失败响应

{
  "code": 1201004,
  "message": "Missing secret",
  "data": {}
}

错误码说明

错误码	HTTP 状态码	消息（英文）	说明
1201004	401	`Missing secret`	请求头缺少 `Authorization` 或格式不是 `Bearer <secret>`
1201005	401	`Invalid secret`	Secret 无效（未找到或已失效）
通用	400	`invalid params`	请求参数校验失败
通用	500	`data server error`	服务端数据库异常

接口列表

所有接口的基础路径：

生产环境：https://openapi.yctou.net/openapi/v2

1. 获取团队应用列表

获取当前团队下所有启用的应用及其关联的分类信息。

GET /openapi/v2/team-applications/options

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "apps": {
      "hits": [
        {
          "team_application_id": 1001,
          "name": "企业CRM",
          "category_ids": [201, 202]
        },
        {
          "team_application_id": 1002,
          "name": "办公OA",
          "category_ids": [203]
        }
      ]
    },
    "categories": {
      "hits": [
        { "id": 201, "name": "业务系统" },
        { "id": 202, "name": "客户管理" },
        { "id": 203, "name": "办公协作" }
      ]
    }
  }
}

响应字段说明

字段	类型	说明
`apps.hits[].team_application_id`	int	应用 ID
`apps.hits[].name`	string	应用名称
`apps.hits[].category_ids`	int[]	关联的分类 ID 列表
`categories.hits[].id`	int	分类 ID
`categories.hits[].name`	string	分类名称

2. 创建账号密码

创建一个新的账号密码记录（Vault），包含账号信息、关联的应用、授权成员/分组。

POST /openapi/v2/vault

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`
`Content-Type`	`application/json`

请求 Body

{
  "account": "admin@example.com",
  "alias": "管理员账号",
  "password": "mypassword123",
  "team_application_ids": [1001, 1002],
  "group_status_id": 1,
  "member_ids": [3001, 3002],
  "group_ids": [4001],
  "category_ids": [201]
}

请求参数

字段	类型	必填	说明
`account`	string	是	账号，最长 50 字符
`alias`	string	是	别名/名称，最长 50 字符
`password`	string	否	密码，最长 50 字符。加密存储（使用账号前 16 位作为 AES-CBC 密钥）
`account_id`	string	否	外部账号 ID
`team_application_ids`	int[]	是	关联的应用 ID 列表（至少 1 个）
`group_status_id`	int	否	授权模式：0=关闭授权, 1=开启授权, 2=条件授权（默认 0）
`member_ids`	int[]	否	授权成员 ID 列表（group_status_id=1 时生效）
`group_ids`	int[]	否	授权分组 ID 列表（group_status_id=1 时生效）
`category_ids`	int[]	否	账号分类 ID 列表

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "key_id": "1234567890"
  }
}

字段	类型	说明
`key_id`	string	新创建的账号密码唯一标识

3. 获取账号密码列表

分页查询当前团队下的账号密码列表，支持关键字搜索和类型筛选。

GET /openapi/v2/vault?page=1&size=20&keyword=admin&type_id=0

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`

查询参数

参数	类型	必填	说明
`page`	int	是	页码，从 1 开始
`size`	int	是	每页数量，最少 1 最多 100
`keyword`	string	否	搜索关键词
`keyword_type`	int	否	搜索范围：0=按别名搜索, 1=按账号搜索（默认 0）
`type_id`	int	否	类型筛选：0=账号密码, 1=SMS 验证码

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 42,
    "hits": [
      {
        "key_id": "1234567890",
        "account": "admin@example.com",
        "account_id": "ext001",
        "alias": "管理员账号",
        "description": "这是管理员的登录凭证",
        "status_id": 1,
        "type_id": 0,
        "is_empty_pwd": 0,
        "update_time": 1700000000,
        "apps": [
          {
            "team_application_id": "1001",
            "name": "企业CRM",
            "url": "https://crm.example.com",
            "group_status_id": 1,
            "status_id": 1
          }
        ]
      }
    ]
  }
}

响应字段说明

字段	类型	说明
`total`	int	符合条件的记录总数
`hits[].key_id`	string	账号密码唯一标识
`hits[].account`	string	账号
`hits[].account_id`	string	外部账号 ID
`hits[].alias`	string	别名
`hits[].description`	string	描述
`hits[].status_id`	int	状态
`hits[].type_id`	int	类型：0=账号密码, 1=SMS
`hits[].is_empty_pwd`	int	是否空密码：0=有密码, 1=无密码
`hits[].update_time`	int	更新时间（Unix 时间戳）
`hits[].apps[].team_application_id`	string	关联的应用 ID
`hits[].apps[].name`	string	应用名称
`hits[].apps[].url`	string	应用 URL
`hits[].apps[].group_status_id`	int	授权状态
`hits[].apps[].status_id`	int	绑定状态

4. 获取账号分类列表

获取当前团队下可用的账号分类列表（type_id=3 的分类，即 Vault 专用分类）。

GET /openapi/v2/vault/categories

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "hits": [
      { "id": 201, "name": "业务系统" },
      { "id": 202, "name": "客户管理" }
    ]
  }
}

字段	类型	说明
`hits[].id`	int	分类 ID
`hits[].name`	string	分类名称

5. 账号密码-应用授权

对指定账号密码在指定应用上设置成员授权和分组授权。

POST /openapi/v2/vault/grant

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`
`Content-Type`	`application/json`

请求 Body

{
  "key_id": 1234567890,
  "team_application_id": 1001,
  "group_status_id": 1,
  "member_ids": [3001, 3002],
  "group_ids": [4001]
}

请求参数

字段	类型	必填	说明
`key_id`	int	是	账号密码 ID
`team_application_id`	int	是	团队应用 ID
`group_status_id`	int	是	授权状态：0=关闭授权, 1=开启授权, 2=条件授权
`member_ids`	int[]	否	授权成员 ID 列表（group_status_id=1 时生效）
`group_ids`	int[]	否	授权分组 ID 列表（group_status_id=1 时生效）

响应

{
  "code": 0,
  "message": "success",
  "data": {}
}

6. 获取组织部门架构

获取当前团队的组织架构树，包含部门节点和成员节点。

GET /openapi/v2/team/department?type=-1

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`

查询参数

参数	类型	必填	说明
`type`	int	否	部门类型筛选。不传或传 `-1` 表示获取所有类型

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "hits": [
      {
        "id": "100",
        "dept_id": "100",
        "name": "总公司",
        "group_id": "100",
        "parent_department_id": "0",
        "member_count": 5,
        "total_member_count": 20,
        "is_group": true,
        "depth": 0,
        "type_id": 1,
        "open_id": "dept_001",
        "children": []
      },
      {
        "id": "5001",
        "name": "张三",
        "dept_id": "100",
        "parent_department_id": "100",
        "depth": 1,
        "is_group": false,
        "type_id": 2,
        "open_id": "member_001"
      }
    ]
  }
}

响应字段说明

字段	类型	说明
`hits[].id`	string	节点 ID（部门时为分组ID，成员时为成员ID）
`hits[].dept_id`	string	部门 ID（仅部门节点）
`hits[].name`	string	部门名称或成员姓名
`hits[].group_id`	string	分组 ID
`hits[].parent_department_id`	string	父部门 ID
`hits[].member_count`	int	部门直接成员数
`hits[].total_member_count`	int	部门总成员数（含子部门）
`hits[].is_group`	bool	`true`=部门节点, `false`=成员节点
`hits[].is_grant`	bool	是否已授权
`hits[].path`	string	节点路径
`hits[].depth`	int	节点深度（0=根部门）
`hits[].type_id`	int	类型 ID
`hits[].open_id`	string	开放 ID（第三方集成用）

7. 获取短信列表

获取当前团队近 10 分钟内的短信验证码记录，支持按手机号模糊搜索。

GET /openapi/v2/sms/list?mobile=138

请求 Headers

Header	值
`Authorization`	`Bearer <secret>`

查询参数

参数	类型	必填	说明
`mobile`	string	否	手机号模糊搜索（非必填，不传返回全部）

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 9001,
      "mobile": "13800138000",
      "content": "【洋葱】您的验证码是 123456",
      "receive_time": 1700000000000,
      "team_application_id": 1001,
      "team_application_name": "企业CRM"
    }
  ]
}

字段	类型	说明
`id`	int	短信记录 ID
`mobile`	string	手机号
`content`	string	短信内容
`receive_time`	int	接收时间（Unix 毫秒时间戳）
`team_application_id`	int	关联的应用 ID
`team_application_name`	string	关联的应用名称

注意：仅返回最近 10 分钟内的短信记录，按接收时间倒序排列。

附录：数据模型

统一响应结构 `Response`

{
  "code": 0,
  "message": "success",
  "data": {}
}

列表响应 `List`

{
  "hits": []
}

分页响应 `ListWithTotal`

{
  "total": 100,
  "hits": []
}

文档内容是否对您有帮助？

是

否

如果遇到产品相关问题，您可咨询在线客服寻求帮助。

洋葱头openAPI接口文档

目录

快速开始

前置条件

第一条 API 请求

鉴权方式

通用响应格式

成功响应

失败响应

错误码说明

接口列表

1. 获取团队应用列表

2. 创建账号密码

3. 获取账号密码列表

4. 获取账号分类列表

5. 账号密码-应用授权

6. 获取组织部门架构

7. 获取短信列表

附录：数据模型

统一响应结构 Response

列表响应 List

分页响应 ListWithTotal

统一响应结构 `Response`

列表响应 `List`

分页响应 `ListWithTotal`