Skip to content
凭据管理系统 文档

读取机密信息或目录

读取当前机密值、列出目录子项，或者通过资源路径后缀 /versions 与 /versions/{version} 列出和读取历史版本。

更新于 查看 Markdown
GET/api/v1/secret/{resource_path...}
使用 App Header 签名或 App Secret需要 unsealed

Path 参数

resource_path必填

string

机密信息或目录路径；可追加 /versions 或 /versions/{version} 访问历史版本

示例："production/orders/database"

Query 参数

cursor可选

string

上一页响应返回的不透明分页游标

示例："<next_cursor>"

limit可选

int

单页返回数量

默认值：50

示例：50

order可选

string

排序方向：asc 或 desc

示例："asc"

q可选

string

按名称或路径搜索

示例："orders"

sort可选

string

排序字段

示例："path"

成功响应

HTTP 200 · 读取当前机密值

根据资源路径返回机密值、目录子项或版本信息

{
  "data": {
    "item": {
      "data": {
        "endpoint": "db.internal:5432",
        "password": "<数据库密码>",
        "username": "orders_app"
      },
      "digest": "sm3:<hex-digest>",
      "metadata": {
        "contact_email": "owner@example.com",
        "contact_name": "张三",
        "contact_phone": "13800000000",
        "created_at": "2026-08-01T08:00:00Z",
        "created_by": "app_orders",
        "current_version": 3,
        "department": "平台工程部",
        "description": "生产订单服务连接数据库使用",
        "labels": {
          "environment": "production"
        },
        "metadata": {
          "ticket": "SEC-1001"
        },
        "name": "订单数据库凭据",
        "organization": "示例科技",
        "path": "production/orders/database",
        "status": "active",
        "updated_at": "2026-08-02T08:00:00Z",
        "updated_by": "app_orders",
        "version": 2
      },
      "path": "production/orders/database",
      "version": 3
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 200 · 列出目录子项

根据资源路径返回机密值、目录子项或版本信息

{
  "data": {
    "items": [
      {
        "current_version": 3,
        "name": "database",
        "path": "production/orders/database",
        "status": "active",
        "type": "secret"
      }
    ],
    "page": {
      "has_more": false,
      "limit": 50,
      "next_cursor": ""
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 200 · 列出历史版本

根据资源路径返回机密值、目录子项或版本信息

{
  "data": {
    "items": [
      {
        "created_at": "2026-08-02T08:00:00Z",
        "created_by": "app_orders",
        "deleted_at": null,
        "destroyed_at": null,
        "digest": "sm3:<hex-digest>",
        "version": 3
      }
    ],
    "page": {
      "has_more": false,
      "limit": 50,
      "next_cursor": ""
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 200 · 读取指定历史版本

根据资源路径返回机密值、目录子项或版本信息

{
  "data": {
    "item": {
      "data": {
        "endpoint": "db.internal:5432",
        "password": "<历史数据库密码>",
        "username": "orders_app"
      },
      "digest": "sm3:<hex-digest>",
      "metadata": {
        "contact_email": "owner@example.com",
        "contact_name": "张三",
        "contact_phone": "13800000000",
        "created_at": "2026-08-01T08:00:00Z",
        "created_by": "app_orders",
        "current_version": 3,
        "department": "平台工程部",
        "description": "生产订单服务连接数据库使用",
        "labels": {
          "environment": "production"
        },
        "metadata": {
          "ticket": "SEC-1001"
        },
        "name": "订单数据库凭据",
        "organization": "示例科技",
        "path": "production/orders/database",
        "status": "active",
        "updated_at": "2026-08-02T08:00:00Z",
        "updated_by": "app_orders",
        "version": 2
      },
      "path": "production/orders/database",
      "version": 2
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

失败响应

按 HTTP status 和 error.code 区分失败原因；响应始终使用统一 envelope。

HTTP 400 · invalid_request

请求参数或 JSON 请求体无效

{
  "data": null,
  "error": {
    "code": "invalid_request",
    "details": {},
    "message": "请求参数或 JSON 请求体无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 400 · not_initialized

系统尚未初始化

{
  "data": null,
  "error": {
    "code": "not_initialized",
    "details": {},
    "message": "系统尚未初始化"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 401 · replayed_request

签名请求的 nonce 已被使用

{
  "data": null,
  "error": {
    "code": "replayed_request",
    "details": {},
    "message": "签名请求的 nonce 已被使用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 401 · unauthorized

App ID、App Secret 或签名无效，或者凭据已过期

{
  "data": null,
  "error": {
    "code": "unauthorized",
    "details": {},
    "message": "App ID、App Secret 或签名无效，或者凭据已过期"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 403 · forbidden

App 没有访问目标资源所需的权限

{
  "data": null,
  "error": {
    "code": "forbidden",
    "details": {},
    "message": "App 没有访问目标资源所需的权限"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 404 · not_found

机密信息、目录或指定版本不存在

{
  "data": null,
  "error": {
    "code": "not_found",
    "details": {},
    "message": "机密信息、目录或指定版本不存在"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 409 · conflict

机密信息路径或当前状态发生冲突

{
  "data": null,
  "error": {
    "code": "conflict",
    "details": {},
    "message": "机密信息路径或当前状态发生冲突"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 413 · request_body_too_large

请求体超过服务端限制

{
  "data": null,
  "error": {
    "code": "request_body_too_large",
    "details": {},
    "message": "请求体超过服务端限制"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 423 · sealed

系统处于封印状态

{
  "data": null,
  "error": {
    "code": "sealed",
    "details": {},
    "message": "系统处于封印状态"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 500 · internal_error

服务端无法完成请求

{
  "data": null,
  "error": {
    "code": "internal_error",
    "details": {},
    "message": "服务端无法完成请求"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 503 · leader_unavailable

高可用集群的 Leader 暂不可用

{
  "data": null,
  "error": {
    "code": "leader_unavailable",
    "details": {},
    "message": "高可用集群的 Leader 暂不可用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 503 · maintenance_mode

系统处于维护模式

{
  "data": null,
  "error": {
    "code": "maintenance_mode",
    "details": {},
    "message": "系统处于维护模式"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
Navigation

Type to search…

↑↓ navigate↵ selectEsc close