Skip to content
MCP Gateway

Safely disable or revoke a client surface, audit the reason, and publish revocation impact.

POST
/v1/client-surfaces/{client_surface_id}/lifecycle

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
client_surface_id
required
string
>= 1 characters

Query Parameters

Section titled “Query Parameters ”
environment_id
required
string
>= 1 characters

Request Body required

Section titled “Request Body required ”
object
requestId
required
string
>= 1 characters
action
required
Allowed values: disable revoke
reasonCode
required
string
/^[a-z0-9_]+$/
reason
required
string
>= 1 characters
terminateActiveSessions
boolean
default: true
correlationId
string

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Lifecycle action accepted, audited, and routed to revocation/session handling.

object
schemaVersion
required
clientSurfaceId
required
string
>= 1 characters
lifecycleAction
required
Allowed values: disable revoke
fromState
required
string
Allowed values: submitted under_review approved rejected disabled revoked archived
toState
required
string
Allowed values: submitted under_review approved rejected disabled revoked archived
reasonCode
required
string
/^[a-z0-9_]+$/
actorId
required

Derived from the authenticated admin actor

string
>= 1 characters
actorRole
required
Allowed values: owner reviewer platform_admin system
auditEventId
required
string
>= 1 characters
revocationId
string
blocksNewCalls
required
boolean
terminatesActiveSessions
required
boolean
affectedClientSessionIds
Array<string>
affectedBackendSessionIds
Array<string>
redactionStatus
required

400

Section titled “400 ”

Invalid lifecycle action or missing reason.

object
schemaVersion
required
requestId
required
string
>= 1 characters
status
required
integer
>= 400 <= 599
reasonCode
required
string
/^[a-z0-9_]+$/
message
required
string
>= 1 characters
retryable
required
boolean
machineSafe
required
boolean
redactionStatus
required
Allowed values: redacted metadata_only
field

Optional metadata-only field identifier for validation errors.

string
details

Optional metadata-only diagnostic details. Never include secret material, payloads, prompts, raw endpoint URLs, or customer data.

object
requiredAction
string
>= 1 characters
resourceRef
string
>= 1 characters
key
additional properties
One of:
string

403

Section titled “403 ”

Actor lacks disable or revoke permission.

object
schemaVersion
required
requestId
required
string
>= 1 characters
status
required
integer
>= 400 <= 599
reasonCode
required
string
/^[a-z0-9_]+$/
message
required
string
>= 1 characters
retryable
required
boolean
machineSafe
required
boolean
redactionStatus
required
Allowed values: redacted metadata_only
field

Optional metadata-only field identifier for validation errors.

string
details

Optional metadata-only diagnostic details. Never include secret material, payloads, prompts, raw endpoint URLs, or customer data.

object
requiredAction
string
>= 1 characters
resourceRef
string
>= 1 characters
key
additional properties
One of:
string

404

Section titled “404 ”

Surface is absent or outside the caller tenant/environment scope.

object
schemaVersion
required
requestId
required
string
>= 1 characters
status
required
integer
>= 400 <= 599
reasonCode
required
string
/^[a-z0-9_]+$/
message
required
string
>= 1 characters
retryable
required
boolean
machineSafe
required
boolean
redactionStatus
required
Allowed values: redacted metadata_only
field

Optional metadata-only field identifier for validation errors.

string
details

Optional metadata-only diagnostic details. Never include secret material, payloads, prompts, raw endpoint URLs, or customer data.

object
requiredAction
string
>= 1 characters
resourceRef
string
>= 1 characters
key
additional properties
One of:
string

Type set in Geist, Source Serif 4, and Departure Mono.