--- title: "创建数据库动态凭据" description: "根据指定数据库动态角色创建一组临时用户名和密码。密码只在本次成功响应中返回，请立即安全保存。" --- > 文档索引 > 完整文档索引：http://127.0.0.1:4321/docs/llms.txt # 创建数据库动态凭据 根据指定数据库动态角色创建一组临时用户名和密码。密码只在本次成功响应中返回，请立即安全保存。 **POST /api/v1/database/roles/{role_id}/credentials** - 模块：数据库凭据（Database） - 认证：使用 App Header 签名或 App Secret - 系统状态：需要 unsealed ## 请求示例 ```bash curl --request POST \ 'http://127.0.0.1:7770/api/v1/database/roles/019fb18d-6b45-7e2d-a3b4-c5d6e7f80910/credentials' \ --header 'X-QK-AppID: $APP_ID' \ --header 'X-QK-Timestamp: $TIMESTAMP' \ --header 'X-QK-Nonce: $NONCE' \ --header 'X-QK-Signature: $SIGNATURE' \ --header 'Content-Type: application/json' \ --data '{ "ttl": "1h" }' ``` ## Path 参数 | 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | | `role_id` | `string` | 是 | 否 | — | 数据库动态角色 ID | ## Query 参数 无。 ## Body 参数 | 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | | `ttl` | `string` | 否 | 否 | — | 本次动态凭据的有效期，例如 30m、1h；省略时使用角色默认值 | ## 成功响应 ### HTTP 201 已创建数据库动态凭据 ```json { "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` 无法按角色配置生成凭据 ```json { "data": null, "error": { "code": "credential_generation_failed", "details": {}, "message": "无法按角色配置生成凭据" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 400 · `credential_policy_invalid` 密码策略配置无效 ```json { "data": null, "error": { "code": "credential_policy_invalid", "details": {}, "message": "密码策略配置无效" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 400 · `credential_template_invalid` 用户名模板配置无效 ```json { "data": null, "error": { "code": "credential_template_invalid", "details": {}, "message": "用户名模板配置无效" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 400 · `invalid_request` 请求参数或 JSON 请求体无效 ```json { "data": null, "error": { "code": "invalid_request", "details": {}, "message": "请求参数或 JSON 请求体无效" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 400 · `not_initialized` 系统尚未初始化 ```json { "data": null, "error": { "code": "not_initialized", "details": {}, "message": "系统尚未初始化" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 401 · `replayed_request` 签名请求的 nonce 已被使用 ```json { "data": null, "error": { "code": "replayed_request", "details": {}, "message": "签名请求的 nonce 已被使用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 401 · `unauthorized` App ID、App Secret 或签名无效，或者凭据已过期 ```json { "data": null, "error": { "code": "unauthorized", "details": {}, "message": "App ID、App Secret 或签名无效，或者凭据已过期" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 403 · `forbidden` App 没有访问目标资源所需的权限 ```json { "data": null, "error": { "code": "forbidden", "details": {}, "message": "App 没有访问目标资源所需的权限" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 404 · `credential_policy_not_found` 数据库角色引用的密码策略不存在 ```json { "data": null, "error": { "code": "credential_policy_not_found", "details": {}, "message": "数据库角色引用的密码策略不存在" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 404 · `credential_template_not_found` 数据库角色引用的用户名模板不存在 ```json { "data": null, "error": { "code": "credential_template_not_found", "details": {}, "message": "数据库角色引用的用户名模板不存在" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 404 · `not_found` 数据库动态角色或其关联资源不存在 ```json { "data": null, "error": { "code": "not_found", "details": {}, "message": "数据库动态角色或其关联资源不存在" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 409 · `conflict` 数据库动态角色当前不能签发凭据 ```json { "data": null, "error": { "code": "conflict", "details": {}, "message": "数据库动态角色当前不能签发凭据" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 409 · `credential_policy_disabled` 数据库角色引用的密码策略已禁用 ```json { "data": null, "error": { "code": "credential_policy_disabled", "details": {}, "message": "数据库角色引用的密码策略已禁用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 409 · `credential_resource_in_use` 凭据生成资源正在被使用 ```json { "data": null, "error": { "code": "credential_resource_in_use", "details": {}, "message": "凭据生成资源正在被使用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 409 · `credential_template_disabled` 数据库角色引用的用户名模板已禁用 ```json { "data": null, "error": { "code": "credential_template_disabled", "details": {}, "message": "数据库角色引用的用户名模板已禁用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 413 · `request_body_too_large` 请求体超过服务端限制 ```json { "data": null, "error": { "code": "request_body_too_large", "details": {}, "message": "请求体超过服务端限制" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 423 · `sealed` 系统处于封印状态 ```json { "data": null, "error": { "code": "sealed", "details": {}, "message": "系统处于封印状态" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 500 · `internal_error` 服务端无法完成请求 ```json { "data": null, "error": { "code": "internal_error", "details": {}, "message": "服务端无法完成请求" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 503 · `leader_unavailable` 高可用集群的 Leader 暂不可用 ```json { "data": null, "error": { "code": "leader_unavailable", "details": {}, "message": "高可用集群的 Leader 暂不可用" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` ### HTTP 503 · `maintenance_mode` 系统处于维护模式 ```json { "data": null, "error": { "code": "maintenance_mode", "details": {}, "message": "系统处于维护模式" }, "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910" } ``` Source: http://127.0.0.1:4321/docs/api/database/post-roles-by-role-id-credentials/