CDNCA

API reference

/v1/sdk-shield

17 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/sdk-shield/appsList SDK apps with today's handshakes (tenants also get their quota)Session
POST/v1/sdk-shield/appsCreate an app; the first AppSecret is returned onceSession
GET/v1/sdk-shield/apps/{id}Read an appSession
PATCH/v1/sdk-shield/apps/{id}Update name, status or protection parametersSession
DELETE/v1/sdk-shield/apps/{id}Delete an app without bound forwards (409 sdk_shield_app_in_use)Session
GET/v1/sdk-shield/apps/{id}/blocksRefusals per minute and node with source samples (at most one day)Session
GET/v1/sdk-shield/apps/{id}/delete-previewWhat the delete confirmation showsSession
GET/v1/sdk-shield/apps/{id}/forwardsList the scope's forwards with why each cannot be boundSession
PUT/v1/sdk-shield/apps/{id}/forwardsReplace the app's forwards (at most 16, of its scope)Session
GET/v1/sdk-shield/apps/{id}/keysList the app's keys with the handshakes each passed in the last 24 hoursSession
POST/v1/sdk-shield/apps/{id}/keysAdd the next key (at most two active: 409 sdk_shield_key_limit); its AppSecret is returned onceSession
POST/v1/sdk-shield/apps/{id}/keys/{key_id}/revokeRevoke a key; the last active one cannot be (409 sdk_shield_last_key)Session
GET/v1/sdk-shield/apps/{id}/node-list/previewThe node list that would be signed now, with node names and the public URLSession
GET/v1/sdk-shield/apps/{id}/statsTotals, refusal reasons, trend and top sources (at most 31 days)Session
GET/v1/sdk-shield/moduleRead the module state (answers without the module)Session
GET/v1/sdk-shield/sdkList the SDK packages and the list signing public keys they embedSession
GET/v1/sdk-shield/sdk/files/{name}Download one SDK archive shipped with this controller releaseSession

Contract file：api/control-sdk-shield.openapi.yaml

Operation details

GET /v1/sdk-shield/apps

List SDK apps with today's handshakes (tenants also get their quota)

operationId
listSDKShieldApps
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Responses

listSDKShieldApps Responses
StatusDescription
200Apps

Fields：items: array<App> quota?: Quota

401Error
403Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/sdk-shield/apps

Create an app; the first AppSecret is returned once

operationId
createSDKShieldApp
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

A tenant is bounded by limits.sdk_shield_apps (409 sdk_shield_app_limit); an administrator must name tenant_scope_id. Audited sdkshield.app.create.

Parameters

createSDKShieldApp Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYesOne key per write; resend it to retry a write whose result was not seen. The same key and request (24 hours, per user and operation) answers the resource it created and creates nothing: a Secret then has replayed true and no app_secret (the secret was only in the first answer). The same key with another request: 409 idempotency_conflict. Missing, malformed or repeated: 422 validation_failed (field Idempotency-Key).

Request body

application/json · Required：Yes

createSDKShieldApp Request body
NameTypeRequiredDescription
namestringYes—

Responses

createSDKShieldApp Responses
StatusDescription
201Created

Fields：app: App secret: Secret

401Error
403Error
409Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}

Read an app

operationId
getSDKShieldApp
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

getSDKShieldApp Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

getSDKShieldApp Responses
StatusDescription
200App

Fields：id: string(uuid) app_id: string name: string tenant: Tenant status: string: active / disabled skew_seconds: integer fail_threshold: integer fail_window_seconds: integer ban_seconds: integer handshake_rate_per_second: integer forward_count: integer(int64) active_key_ids: array<integer> today?: Today revision: integer created_at: string(date-time) updated_at: string(date-time)

401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

PATCH /v1/sdk-shield/apps/{id}

Update name, status or protection parameters

operationId
updateSDKShieldApp
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

status disabled makes every bound forward refuse new connections (app_disabled) after the next publication. expected_revision refuses a stale edit (409 revision_conflict). Audited sdkshield.app.update / disable / enable.

Parameters

updateSDKShieldApp Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Request body

application/json · Required：Yes

updateSDKShieldApp Request body
NameTypeRequiredDescription
expected_revisionintegerNo—
namestringNo—
statusstring: active / disabledNo—
skew_secondsintegerNo—
fail_thresholdintegerNo—
fail_window_secondsintegerNo—
ban_secondsintegerNo0 = disconnect only
handshake_rate_per_secondintegerNo0 = no cap

Responses

updateSDKShieldApp Responses
StatusDescription
200Updated

Fields：id: string(uuid) app_id: string name: string tenant: Tenant status: string: active / disabled skew_seconds: integer fail_threshold: integer fail_window_seconds: integer ban_seconds: integer handshake_rate_per_second: integer forward_count: integer(int64) active_key_ids: array<integer> today?: Today revision: integer created_at: string(date-time) updated_at: string(date-time)

401Error
403Error
404Error
409Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

DELETE /v1/sdk-shield/apps/{id}

Delete an app without bound forwards (409 sdk_shield_app_in_use)

operationId
deleteSDKShieldApp
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

Audited sdkshield.app.delete.

Parameters

deleteSDKShieldApp Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

deleteSDKShieldApp Responses
StatusDescription
204Deleted
401Error
403Error
404Error
409Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/blocks

Refusals per minute and node with source samples (at most one day)

operationId
listSDKShieldAppBlocks
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

listSDKShieldAppBlocks Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).
fromquerystring(date-time)NoRFC 3339; default 24 hours before to
toquerystring(date-time)NoRFC 3339; default now
node_idquerystring(uuid)NoOnly this node

Responses

listSDKShieldAppBlocks Responses
StatusDescription
200Blocks, newest first

Fields：items: array<BlockMinute>

401Error
403Error
404Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/delete-preview

What the delete confirmation shows

operationId
previewSDKShieldAppDelete
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

previewSDKShieldAppDelete Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

previewSDKShieldAppDelete Responses
StatusDescription
200Preview

Fields：app: App forward_count: integer(int64) deletable: boolean

401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/forwards

List the scope's forwards with why each cannot be bound

operationId
listSDKShieldAppForwards
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

listSDKShieldAppForwards Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

listSDKShieldAppForwards Responses
StatusDescription
200Forwards

Fields：items: array<Forward>

401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

PUT /v1/sdk-shield/apps/{id}/forwards

Replace the app's forwards (at most 16, of its scope)

operationId
setSDKShieldAppForwards
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

Any incompatible forward refuses the whole change with 422 sdk_shield_forward_incompatible; error.details.forwards lists every one with its reasons (the codes of Forward.incompatible). Binding republishes the scope. Audited sdkshield.forwards.update.

Parameters

setSDKShieldAppForwards Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Request body

application/json · Required：Yes

setSDKShieldAppForwards Request body
NameTypeRequiredDescription
forward_idsarray<string(uuid)>Yes—

Responses

setSDKShieldAppForwards Responses
StatusDescription
200Bound forwards

Fields：forward_ids: array<string(uuid)>

401Error
403Error
404Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/keys

List the app's keys with the handshakes each passed in the last 24 hours

operationId
listSDKShieldAppKeys
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

listSDKShieldAppKeys Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

listSDKShieldAppKeys Responses
StatusDescription
200Keys

Fields：items: array<Key>

401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/sdk-shield/apps/{id}/keys

Add the next key (at most two active: 409 sdk_shield_key_limit); its AppSecret is returned once

operationId
rotateSDKShieldAppKey
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

Audited sdkshield.key.create (key_id only).

Parameters

rotateSDKShieldAppKey Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYesOne key per write; resend it to retry a write whose result was not seen. The same key and request (24 hours, per user and operation) answers the resource it created and creates nothing: a Secret then has replayed true and no app_secret (the secret was only in the first answer). The same key with another request: 409 idempotency_conflict. Missing, malformed or repeated: 422 validation_failed (field Idempotency-Key).
idpathstring(uuid)YesThe app's row id (App.id).

Responses

rotateSDKShieldAppKey Responses
StatusDescription
201New key

Fields：app_id: string key_id: integer app_secret?: string replayed: boolean

401Error
403Error
404Error
409Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/sdk-shield/apps/{id}/keys/{key_id}/revoke

Revoke a key; the last active one cannot be (409 sdk_shield_last_key)

operationId
revokeSDKShieldAppKey
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.manage

Description (from the contract)

Nodes refuse it as unknown_key after the next publication; open connections stay. Audited sdkshield.key.revoke.

Parameters

revokeSDKShieldAppKey Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).
key_idpathintegerYes—

Responses

revokeSDKShieldAppKey Responses
StatusDescription
204Revoked
401Error
403Error
404Error
409Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/node-list/preview

The node list that would be signed now, with node names and the public URL

operationId
previewSDKShieldNodeList
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

previewSDKShieldNodeList Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).

Responses

previewSDKShieldNodeList Responses
StatusDescription
200Preview

Fields：revision: integer issued_at: string(date-time) | null(date-time) expires_at: string(date-time) | null(date-time) refresh_after: integer skew_seconds: integer signing_key_id: string public_path: string public_url?: string nodes: array<PreviewNode> udp_idle_seconds: object truncated: boolean

401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/apps/{id}/stats

Totals, refusal reasons, trend and top sources (at most 31 days)

operationId
getSDKShieldAppStats
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

getSDKShieldAppStats Parameters
NameInTypeRequiredDescription
idpathstring(uuid)YesThe app's row id (App.id).
fromquerystring(date-time)NoRFC 3339; default 24 hours before to
toquerystring(date-time)NoRFC 3339; default now
node_idquerystring(uuid)NoOnly this node
bucketquerystring: minute / hourNoTrend bucket; default minute up to 6 hours, else hour

Responses

getSDKShieldAppStats Responses
StatusDescription
200Statistics

Fields：from: string(date-time) to: string(date-time) bucket: string: minute / hour totals: Totals reasons: array<ReasonCount> trend: array<TrendPoint> top: array<Source>

401Error
403Error
404Error
422Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/module

Read the module state (answers without the module)

operationId
getSDKShieldModule
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Responses

getSDKShieldModule Responses
StatusDescription
200Module state

Fields：licensed: boolean locally_disabled: boolean defaults: Protection signing_keys: array<SigningKey> quota?: Quota

401Error
403Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/sdk

List the SDK packages and the list signing public keys they embed

operationId
getSDKShieldSDKManifest
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Responses

getSDKShieldSDKManifest Responses
StatusDescription
200SDK manifest

Fields：packages: array<SDKPackage> signing_keys: array<SigningKey>

401Error
403Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/sdk-shield/sdk/files/{name}

Download one SDK archive shipped with this controller release

operationId
downloadSDKShieldSDKFile
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

All of：streams.read

Parameters

downloadSDKShieldSDKFile Parameters
NameInTypeRequiredDescription
namepathstringYesArchive file name, the last segment of SDKPackage.url

Responses

downloadSDKShieldSDKFile Responses
StatusDescription
200The archive (Content-Disposition attachment; X-Content-SHA256 is its digest, as in the manifest)
401Error
403Error
404Error
503Error

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list