CDNCA

开放接口

/v1/security-jwt-key-sets

8 个接口 · 8 个接口支持 API Key

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/security-jwt-key-sets列出 JWT 密钥集API Key 可调登录会话
POST/v1/security-jwt-key-sets创建 JWT 密钥集API Key 可调登录会话
GET/v1/security-jwt-key-sets/{set_id}查看 JWT 密钥集API Key 可调登录会话
PUT/v1/security-jwt-key-sets/{set_id}替换 JWT 密钥集API Key 可调登录会话
DELETE/v1/security-jwt-key-sets/{set_id}删除 JWT 密钥集API Key 可调登录会话
GET/v1/security-jwt-key-sets/{set_id}/references列出引用 JWT 密钥集的策略API Key 可调登录会话
POST/v1/security-jwt-key-sets/{set_id}/refresh立即拉取 JWKSAPI Key 可调登录会话
POST/v1/security-jwt-key-sets/{set_id}/test-token用密钥集校验一个令牌API Key 可调登录会话

契约文件：api/openapi/v1/control.yaml

接口详情

GET /v1/security-jwt-key-sets

列出 JWT 密钥集

operationId
listSecurityJWTKeySets
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.read. Tenant identities only. key_count counts the keys of an allowed algorithm (what the nodes get); reference_count the tenant's live policies naming the set.

响应

listSecurityJWTKeySets 响应
状态码说明
200Sets by name.

字段：items: array<SecurityJWTKeySet>

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
500服务内部故障，请求未完成。

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/security-jwt-key-sets

创建 JWT 密钥集

operationId
createSecurityJWTKeySet
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.manage; tenant only. A remote set is fetched once (https, public addresses only, checked after DNS); a failed fetch still creates it with fetch_state failing and no keys, except a URL resolving to a non-public address (validation_error jwks_url blocked_address). A static set takes a JWK Set in jwks: public keys only (a private member refuses it: jwks contains_private_key), RSA 2048-8192 / EC P-256 / Ed25519, at least one of an allowed algorithm (jwks no_usable_key). Other field reasons: jwks_url not_https, jwks invalid_json / too_many_keys. At most 50 live sets per tenant (422 jwt_key_set_limit). Audit security.jwt_key_set.create.

参数

createSecurityJWTKeySet 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createSecurityJWTKeySet 请求体
名称类型必填说明
namestring是—
descriptionstring否—
sourcestring: remote / static是Fixed at creation.
jwks_urlstring(uri)否remote only; https, public address.
refresh_secondsinteger否remote only.
jwksobject否static only; a JWK Set ({keys: [...]}), public keys only, at most 256 KiB.
algorithmsarray<string: RS256 / ES256 / EdDSA>是—
token_sourcesarray<SecurityJWTTokenSource>是The node takes the first token found
issuerstring否Empty skips the iss check.
audiencesarray<string>否Empty skips the aud check.
require_expboolean否—
clock_skew_secondsinteger否—
failure_statusinteger: 403 / 401否What a blocking jwt_invalid rule answers: 403 the block page, 401 with WWW-Authenticate: Bearer.

响应

createSecurityJWTKeySet 响应
状态码说明
201Created, or an identical request replayed.

字段：id: string(uuid) name: string description: string source: string: remote / static jwks_url?: string refresh_seconds?: integer algorithms: array<string> token_sources: array<SecurityJWTTokenSource> issuer?: string audiences: array<string> require_exp: boolean clock_skew_seconds: integer failure_status: integer: 403 / 401 keys: array<SecurityJWTKey> ignored_keys: array<object> key_count: integer keys_revision: integer fetch_state: string: none / ok / failing fetch_failures: integer fetch_error?: string: dns / blocked_address / tls / http_status / too_large / content_type / invalid_json / contains_private_key / no_usable_key / network fetched_at?: string(date-time) next_fetch_at?: string(date-time) refresh_available_at?: string(date-time) reference_count: integer revision: integer updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
422The request is well formed but breaks a business rule (error.code names it).
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/security-jwt-key-sets/{set_id}

查看 JWT 密钥集

operationId
getSecurityJWTKeySet
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.read. The set with its normalized public keys and the keys the last JWKS left out.

参数

getSecurityJWTKeySet 参数
名称位置类型必填说明
set_idpathstring(uuid)是—

响应

getSecurityJWTKeySet 响应
状态码说明
200The set.

字段：id: string(uuid) name: string description: string source: string: remote / static jwks_url?: string refresh_seconds?: integer algorithms: array<string> token_sources: array<SecurityJWTTokenSource> issuer?: string audiences: array<string> require_exp: boolean clock_skew_seconds: integer failure_status: integer: 403 / 401 keys: array<SecurityJWTKey> ignored_keys: array<object> key_count: integer keys_revision: integer fetch_state: string: none / ok / failing fetch_failures: integer fetch_error?: string: dns / blocked_address / tls / http_status / too_large / content_type / invalid_json / contains_private_key / no_usable_key / network fetched_at?: string(date-time) next_fetch_at?: string(date-time) refresh_available_at?: string(date-time) reference_count: integer revision: integer updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PUT /v1/security-jwt-key-sets/{set_id}

替换 JWT 密钥集

operationId
updateSecurityJWTKeySet
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.manage and the current revision. source cannot change. A static set sent without jwks keeps its keys. A remote set whose jwks_url changes is fetched first and refused when that fetch fails (validation_error jwks_url fetch_<category>, or blocked_address). Algorithms leaving no key are refused (algorithms no_usable_key). Every tenant whose bound WAF policy names the set is republished (system trigger jwt_key_set). Audit security.jwt_key_set.update.

参数

updateSecurityJWTKeySet 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
set_idpathstring(uuid)是—

请求体

application/json · 必填：是

updateSecurityJWTKeySet 请求体
名称类型必填说明
namestring是—
descriptionstring否—
sourcestring: remote / static是Fixed at creation.
jwks_urlstring(uri)否remote only; https, public address.
refresh_secondsinteger否remote only.
jwksobject否static only; a JWK Set ({keys: [...]}), public keys only, at most 256 KiB.
algorithmsarray<string: RS256 / ES256 / EdDSA>是—
token_sourcesarray<SecurityJWTTokenSource>是The node takes the first token found
issuerstring否Empty skips the iss check.
audiencesarray<string>否Empty skips the aud check.
require_expboolean否—
clock_skew_secondsinteger否—
failure_statusinteger: 403 / 401否What a blocking jwt_invalid rule answers: 403 the block page, 401 with WWW-Authenticate: Bearer.
expected_revisioninteger是—

响应

updateSecurityJWTKeySet 响应
状态码说明
200Replaced (revision + 1), or an identical request replayed.

字段：id: string(uuid) name: string description: string source: string: remote / static jwks_url?: string refresh_seconds?: integer algorithms: array<string> token_sources: array<SecurityJWTTokenSource> issuer?: string audiences: array<string> require_exp: boolean clock_skew_seconds: integer failure_status: integer: 403 / 401 keys: array<SecurityJWTKey> ignored_keys: array<object> key_count: integer keys_revision: integer fetch_state: string: none / ok / failing fetch_failures: integer fetch_error?: string: dns / blocked_address / tls / http_status / too_large / content_type / invalid_json / contains_private_key / no_usable_key / network fetched_at?: string(date-time) next_fetch_at?: string(date-time) refresh_available_at?: string(date-time) reference_count: integer revision: integer updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/security-jwt-key-sets/{set_id}

删除 JWT 密钥集

operationId
deleteSecurityJWTKeySet
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.manage and the current revision. A set any live policy version names is refused (409 jwt_key_set_in_use). Audit security.jwt_key_set.delete.

参数

deleteSecurityJWTKeySet 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—
set_idpathstring(uuid)是—
expected_revisionqueryinteger是—

响应

deleteSecurityJWTKeySet 响应
状态码说明
204Deleted.
400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/security-jwt-key-sets/{set_id}/references

列出引用 JWT 密钥集的策略

operationId
listSecurityJWTKeySetReferences
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.read. The tenant's live policies with a version naming the set; rule_count is from the latest such version.

参数

listSecurityJWTKeySetReferences 参数
名称位置类型必填说明
set_idpathstring(uuid)是—

响应

listSecurityJWTKeySetReferences 响应
状态码说明
200Policies by name.

字段：items: array<SecurityStringSetReference>

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/security-jwt-key-sets/{set_id}/refresh

立即拉取 JWKS

operationId
refreshSecurityJWTKeySet
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.manage. Remote sets only (409 jwt_key_set_not_remote); once a minute per set (429 refresh_too_frequent, refresh_available_at says when). A failed fetch keeps the last good keys and is returned in fetch_state / fetch_error, not as an error. New keys republish the tenants naming the set. Audit security.jwt_key_set.refresh.

参数

refreshSecurityJWTKeySet 参数
名称位置类型必填说明
set_idpathstring(uuid)是—

响应

refreshSecurityJWTKeySet 响应
状态码说明
200The set after the fetch.

字段：id: string(uuid) name: string description: string source: string: remote / static jwks_url?: string refresh_seconds?: integer algorithms: array<string> token_sources: array<SecurityJWTTokenSource> issuer?: string audiences: array<string> require_exp: boolean clock_skew_seconds: integer failure_status: integer: 403 / 401 keys: array<SecurityJWTKey> ignored_keys: array<object> key_count: integer keys_revision: integer fetch_state: string: none / ok / failing fetch_failures: integer fetch_error?: string: dns / blocked_address / tls / http_status / too_large / content_type / invalid_json / contains_private_key / no_usable_key / network fetched_at?: string(date-time) next_fetch_at?: string(date-time) refresh_available_at?: string(date-time) reference_count: integer revision: integer updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
429refresh_too_frequent.
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 429 被限速：等待后再试，降低并发。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/security-jwt-key-sets/{set_id}/test-token

用密钥集校验一个令牌

operationId
testSecurityJWTToken
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Requires security_policies.read. Verifies the token as the nodes would (same algorithms, keys, issuer, audiences, exp / nbf and skew). The token is not stored, audited or logged.

参数

testSecurityJWTToken 参数
名称位置类型必填说明
set_idpathstring(uuid)是—

请求体

application/json · 必填：是

testSecurityJWTToken 请求体
名称类型必填说明
tokenstring是—

响应

testSecurityJWTToken 响应
状态码说明
200The result.

字段：valid: boolean reason?: string: missing / malformed / alg_not_allowed / key_not_found / bad_signature / expired / exp_required / not_yet_valid / issuer_mismatch / audience_mismatch header?: object claims?: object

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表