{
    "openapi": "3.1.0",
    "info": {
        "title": "Cloudsign OpenAPI · 接入与授权",
        "version": "1.22.0-preview.1",
        "description": "通过用户开放 API 管理自己账号下已授权的企业签名和应用分发资源，完成上传、签名、发布、查询和订单处理。接入前请在开发者中心创建 API 应用并配置权限。\n按产品筛选操作的契约，请求字段、默认值和权限与完整契约一致。应用分发列表须显式传 module=distribution。"
    },
    "servers": [
        {
            "url": "https://{host}",
            "variables": {
                "host": {
                    "default": "www.fenfa.im",
                    "description": "配置的主网站域名，不是分发或存储域名"
                }
            }
        }
    ],
    "security": [
        {
            "AccessKeySignature": []
        }
    ],
    "components": {
        "parameters": {
            "Date": {
                "name": "X-Api-Date",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "date-time"
                },
                "description": "UTC，YYYY-MM-DDTHH:mm:ssZ，前后 300 秒窗口"
            },
            "Nonce": {
                "name": "X-Api-Nonce",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{32}$"
                }
            },
            "BodyHash": {
                "name": "X-Api-Content-Sha256",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                },
                "description": "实际请求体字节的 SHA-256；GET 为零字节摘要"
            },
            "Environment": {
                "name": "X-Api-Environment",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "const": "production"
                }
            },
            "SecurityToken": {
                "name": "X-Api-Security-Token",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string",
                    "pattern": "^CST_[A-Za-z0-9_-]{43}$"
                },
                "description": "Required only for AKT credentials; append SHA256(token) to the canonical string. AKP requests must omit it."
            },
            "Idempotency": {
                "name": "X-Api-Idempotency-Key",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{16,64}$"
                },
                "description": "同一次业务重试保持原值及原始请求体，更换 nonce 重新签名。有效记录保留 90 天。"
            }
        },
        "responses": {
            "Error": {
                "description": "400 请求格式；401 凭据无效/过期；403 未授权；404 资源不存在或不可见；405 方法不支持；409 nonce 重放；429 限流（Retry-After 秒）；503 平台关闭或依赖不可用。通过验签的失败请求也须使用新 nonce 重试。",
                "headers": {
                    "X-Request-Id": {
                        "schema": {
                            "type": "string"
                        }
                    },
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "request_id",
                    "error"
                ],
                "properties": {
                    "request_id": {
                        "type": "string"
                    },
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "SessionList": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "items",
                    "next_cursor"
                ],
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Session"
                        }
                    },
                    "next_cursor": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "pattern": "^AKT[a-f0-9]{40}$"
                    }
                }
            },
            "Session": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "app_id",
                    "name",
                    "actions",
                    "rpm",
                    "created_at",
                    "expires_at",
                    "last_used_at",
                    "state"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^AKT[a-f0-9]{40}$"
                    },
                    "app_id": {
                        "type": "string",
                        "pattern": "^A[a-f0-9]{32}$"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "actions": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "enterprise:ReadApps",
                                "enterprise:ReadVersions",
                                "enterprise:ReadJobs",
                                "distribution:ReadApps",
                                "distribution:ReadVersions",
                                "distribution:ReadSettings",
                                "enterprise:ReadStatistics",
                                "distribution:ReadStatistics",
                                "enterprise:ReadPricing",
                                "distribution:ReadPricing",
                                "enterprise:ReadVersionStatistics"
                            ]
                        }
                    },
                    "rpm": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 60
                    },
                    "created_at": {
                        "type": "integer"
                    },
                    "expires_at": {
                        "type": "integer"
                    },
                    "last_used_at": {
                        "type": "integer"
                    },
                    "state": {
                        "type": "string",
                        "enum": [
                            "active",
                            "expired",
                            "revoked"
                        ]
                    }
                }
            },
            "SessionIssued": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "app_id",
                    "name",
                    "actions",
                    "rpm",
                    "created_at",
                    "expires_at",
                    "last_used_at",
                    "state",
                    "credentials"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^AKT[a-f0-9]{40}$"
                    },
                    "app_id": {
                        "type": "string",
                        "pattern": "^A[a-f0-9]{32}$"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "actions": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "enterprise:ReadApps",
                                "enterprise:ReadVersions",
                                "enterprise:ReadJobs",
                                "distribution:ReadApps",
                                "distribution:ReadVersions",
                                "distribution:ReadSettings",
                                "enterprise:ReadStatistics",
                                "distribution:ReadStatistics",
                                "enterprise:ReadPricing",
                                "distribution:ReadPricing",
                                "enterprise:ReadVersionStatistics"
                            ]
                        }
                    },
                    "rpm": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 60
                    },
                    "created_at": {
                        "type": "integer"
                    },
                    "expires_at": {
                        "type": "integer"
                    },
                    "last_used_at": {
                        "type": "integer"
                    },
                    "state": {
                        "type": "string",
                        "enum": [
                            "active",
                            "expired",
                            "revoked"
                        ]
                    },
                    "credentials": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "access_key_id",
                                    "access_key_secret",
                                    "security_token"
                                ],
                                "properties": {
                                    "access_key_id": {
                                        "type": "string",
                                        "pattern": "^AKT[a-f0-9]{40}$"
                                    },
                                    "access_key_secret": {
                                        "type": "string",
                                        "pattern": "^CSK_[A-Za-z0-9_-]{43}$"
                                    },
                                    "security_token": {
                                        "type": "string",
                                        "pattern": "^CST_[A-Za-z0-9_-]{43}$"
                                    }
                                }
                            }
                        ]
                    }
                }
            },
            "SessionInput": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "name",
                    "actions",
                    "networks",
                    "duration_seconds",
                    "rpm"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 80
                    },
                    "actions": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "enterprise:ReadApps",
                                "enterprise:ReadVersions",
                                "enterprise:ReadJobs",
                                "distribution:ReadApps",
                                "distribution:ReadVersions",
                                "distribution:ReadSettings",
                                "enterprise:ReadStatistics",
                                "distribution:ReadStatistics",
                                "enterprise:ReadPricing",
                                "distribution:ReadPricing",
                                "enterprise:ReadVersionStatistics"
                            ]
                        }
                    },
                    "networks": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 50
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "minimum": 60,
                        "maximum": 3600
                    },
                    "rpm": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 60
                    }
                }
            },
            "SessionRevoked": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "revoked"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^AKT[a-f0-9]{40}$"
                    },
                    "revoked": {
                        "type": "boolean",
                        "const": true
                    }
                }
            }
        },
        "securitySchemes": {
            "AccessKeySignature": {
                "type": "apiKey",
                "in": "header",
                "name": "Authorization",
                "description": "CS1-HMAC-SHA256 Credential=AKP<40hex> 或 AKT<40hex>,Signature=<64hex>。签入 Host、路径、规范查询和 X-Api-* 字段。AKT 必须携带 X-Api-Security-Token，并在 canonical 原有结尾追加换行和 Token 的 SHA-256 摘要；AKP 不携带该头。Secret 不发送给 API。"
            }
        }
    },
    "paths": {
        "/api/v1/whoami": {
            "get": {
                "operationId": "getIdentity",
                "summary": "查询当前身份与权限",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "$ref": "#/components/parameters/SecurityToken"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "身份校验成功（不要求额外业务动作权限）",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "owner_id": {
                                                    "type": "integer"
                                                },
                                                "actions": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "resources": {
                                                    "oneOf": [
                                                        {
                                                            "type": "string",
                                                            "const": "*"
                                                        },
                                                        {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    ]
                                                },
                                                "environment": {
                                                    "type": "string",
                                                    "const": "production"
                                                }
                                            },
                                            "required": [
                                                "owner_id",
                                                "actions",
                                                "resources",
                                                "environment"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "description": "首次接入时先调用此接口。用 owner_id 核对账号，用 actions 和 resources 核对操作及应用范围。之后可调用列出应用取得业务应用 ID。",
                "tags": [
                    "接入与授权"
                ],
                "x-cloudsign-products": [
                    "access"
                ]
            }
        },
        "/api/v1/apps/{app_id}/sessions": {
            "get": {
                "operationId": "listSessions",
                "summary": "列出已签发的只读凭据",
                "description": "使用签发凭据的父 AKP，读取当前 API 应用在指定业务应用下的会话状态、到期时间和最近使用时间。可从列表获取撤销所需的 AKT 标识。",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "name": "app_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^A[a-f0-9]{32}$"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^AKT[a-f0-9]{40}$"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/SecurityToken"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "查询成功；不包含安装包下载 URL、证书或私有内部信息",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/SessionList"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "tags": [
                    "接入与授权"
                ],
                "x-cloudsign-products": [
                    "access"
                ]
            },
            "post": {
                "operationId": "createSession",
                "summary": "签发单应用只读凭据",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "name": "app_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^A[a-f0-9]{32}$"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Idempotency"
                    },
                    {
                        "$ref": "#/components/parameters/SecurityToken"
                    }
                ],
                "description": "为一个自有应用签发 AKT，选择父密钥已具备的只读动作、时长、网络和限额。首次成功立即安全保存完整 credentials。响应丢失时先查会话并撤销，再用新幂等键签发。",
                "responses": {
                    "200": {
                        "description": "成功受理；异步操作须继续查询状态",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/SessionIssued"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SessionInput"
                            }
                        }
                    }
                },
                "tags": [
                    "接入与授权"
                ],
                "x-cloudsign-products": [
                    "access"
                ]
            }
        },
        "/api/v1/apps/{app_id}/sessions/{session_id}/revoke": {
            "post": {
                "operationId": "revokeSession",
                "summary": "撤销单个只读凭据",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Date"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/BodyHash"
                    },
                    {
                        "$ref": "#/components/parameters/Environment"
                    },
                    {
                        "name": "app_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^A[a-f0-9]{32}$"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Idempotency"
                    },
                    {
                        "name": "session_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^AKT[a-f0-9]{40}$"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/SecurityToken"
                    }
                ],
                "description": "从会话列表取得 AKT 标识，在路径中同时指定对应的业务应用，正文传空对象。撤销成功后该会话不能继续读取应用数据。",
                "responses": {
                    "200": {
                        "description": "成功受理；异步操作须继续查询状态",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": [
                                        "request_id",
                                        "data"
                                    ],
                                    "properties": {
                                        "request_id": {
                                            "type": "string",
                                            "pattern": "^[a-f0-9]{32}$"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/SessionRevoked"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {}
                            }
                        }
                    }
                },
                "tags": [
                    "接入与授权"
                ],
                "x-cloudsign-products": [
                    "access"
                ]
            }
        }
    },
    "x-cloudsign-webhooks": "webhooks-v1.json",
    "tags": [
        {
            "name": "接入与授权",
            "description": "确认当前调用身份，管理本人应用范围内的只读临时凭据。AccessKey 签名、OAuth、Webhook 与沙箱说明见接入指南，各自遵守既有授权和准入。"
        }
    ],
    "x-cloudsign-product": "access"
}
