Skip to content
凭据管理系统 文档

创建数据库动态凭据

根据指定数据库动态角色创建一组临时用户名和密码。密码只在本次成功响应中返回，请立即安全保存。

更新于 查看 Markdown
POST/api/v1/database/roles/{role_id}/credentials
使用 App Header 签名或 App Secret需要 unsealed

Path 参数

role_id必填

string

数据库动态角色 ID

示例："019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"

Body 参数

ttl可选

string

本次动态凭据的有效期，例如 30m、1h；省略时使用角色默认值

示例："1h"

成功响应

HTTP 201

已创建数据库动态凭据

{
  "data": {
    "item": {
      "connection_id": "019fb17c-6c18-7c59-a848-998877665544",
      "created_at": "2026-08-02T08:00:00Z",
      "created_by": "app_orders",
      "driver_type": "postgresql",
      "expires_at": "2026-08-02T09:00:00Z",
      "id": "019fb190-0f55-7b8a-a8b4-112233445566",
      "issue_time": "2026-08-02T08:00:00Z",
      "issued_to_principal_id": "app_orders",
      "issued_to_principal_type": "app",
      "last_error": "",
      "lease_id": "019fb190-6de4-7cb9-b92b-aabbccddeeff",
      "metadata": {},
      "password": "<仅返回一次的数据库密码>",
      "role_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910",
      "status": "active",
      "updated_at": "2026-08-02T08:00:00Z",
      "updated_by": "app_orders",
      "username": "app_orders_a8f2",
      "version": 1
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

失败响应

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

HTTP 400 · credential_generation_failed

无法按角色配置生成凭据

{
  "data": null,
  "error": {
    "code": "credential_generation_failed",
    "details": {},
    "message": "无法按角色配置生成凭据"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 400 · credential_policy_invalid

密码策略配置无效

{
  "data": null,
  "error": {
    "code": "credential_policy_invalid",
    "details": {},
    "message": "密码策略配置无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 400 · credential_template_invalid

用户名模板配置无效

{
  "data": null,
  "error": {
    "code": "credential_template_invalid",
    "details": {},
    "message": "用户名模板配置无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

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 · credential_policy_not_found

数据库角色引用的密码策略不存在

{
  "data": null,
  "error": {
    "code": "credential_policy_not_found",
    "details": {},
    "message": "数据库角色引用的密码策略不存在"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 404 · credential_template_not_found

数据库角色引用的用户名模板不存在

{
  "data": null,
  "error": {
    "code": "credential_template_not_found",
    "details": {},
    "message": "数据库角色引用的用户名模板不存在"
  },
  "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 409 · credential_policy_disabled

数据库角色引用的密码策略已禁用

{
  "data": null,
  "error": {
    "code": "credential_policy_disabled",
    "details": {},
    "message": "数据库角色引用的密码策略已禁用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 409 · credential_resource_in_use

凭据生成资源正在被使用

{
  "data": null,
  "error": {
    "code": "credential_resource_in_use",
    "details": {},
    "message": "凭据生成资源正在被使用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}

HTTP 409 · credential_template_disabled

数据库角色引用的用户名模板已禁用

{
  "data": null,
  "error": {
    "code": "credential_template_disabled",
    "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