For AI agents: markdown of this page — /docs-content-en/infra/access/audience-proposals.md documentation index — /llms.txt

Check or cancel an audience request

GET /v1/infra/servers/:id/audience-proposals/:proposalId

POST /v1/infra/servers/:id/audience-proposals/:proposalId/cancel

Let the original API key read or cancel its own request to change application access. The original operation returns proposalId in error.details.proposalId with 409 AUDIENCE_APPROVAL_REQUIRED. Another key belonging to the same owner cannot access the request.

An API key cannot approve a request. A signed-in person makes that decision in their account. APPROVED means consent has been given, not that the change has been applied: retry the original operation with the same key, exact parameters and approvalId. Cancellation itself does not change access.

Parameters

Parameter In Type Required Description
id path string (UUID) yes Server ID from the original operation; see List servers
proposalId path string (UUID) yes Request ID from error.details.proposalId

The cancellation body is optional. If provided, it must be an empty object {}. The verified X-Api-Key identifies the caller; body fields cannot supply an identity.

Examples

curl — check

Terminal 
curl "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/audience-proposals/PROPOSAL_ID"   -H "X-Api-Key: YOUR_API_KEY"

curl — cancel

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/audience-proposals/PROPOSAL_ID/cancel"   -H "X-Api-Key: YOUR_API_KEY"

JavaScript — check

javascript 
const response = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/audience-proposals/${proposalId}`,
  { headers: { 'X-Api-Key': apiKey } },
)
const { proposal } = await response.json()
console.log(proposal.state)

JavaScript — cancel

javascript 
const response = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/audience-proposals/${proposalId}/cancel`,
  { method: 'POST', headers: { 'X-Api-Key': apiKey } },
)
const { proposal } = await response.json()
console.log(proposal.state)

Response fields

A successful response is { "proposal": ... }, without a success or data envelope. The table lists the main fields; the response also includes the exact operation, original, proposed and current access snapshots, participant labels and differences.

Field Type Description
proposal.id string (UUID) Request ID
proposal.state string PENDING, APPROVED, APPLIED, REJECTED, CANCELLED, EXPIRED or STALE
proposal.baseRevision string Access revision when the request was created; a decimal string
proposal.currentRevision string Current access revision; a decimal string
proposal.expiresAt string Request expiry in ISO 8601
proposal.canDecide boolean Always false for an API key
proposal.canCancel boolean Whether the request can be cancelled now
proposal.resultEntityId string (UUID), optional ID of the record created when applied; not a token or secret URL

Response example

Only the ID, state and revisions from the status response are shown below:

JSON 
{
  "proposal": {
    "id": "00000000-0000-4000-8000-000000000001",
    "state": "PENDING",
    "baseRevision": "0",
    "currentRevision": "0"
  }
}

Successful cancellation returns the CANCELLED state.

Error response example

404 — the request does not exist or belongs to another caller:

JSON 
{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Proposal not found" }
}

Errors

HTTP Code Description
400 VALIDATION_ERROR Invalid UUID or a nonempty cancellation body
401 MISSING_API_KEY No key was supplied
401 INVALID_API_KEY The key was not recognized
403 AUDIENCE_APPROVAL_FORBIDDEN The current key, its owner or portal binding no longer permits the operation
404 NOT_FOUND No server or request in the required portal, or the request was created by another caller
409 AUDIENCE_APPROVAL_REPLAY Cancellation: the request was already applied, cancelled or completed by another decision
409 AUDIENCE_APPROVAL_STALE Cancellation: the access revision changed
410 AUDIENCE_APPROVAL_EXPIRED Cancellation: the request expired

For common API errors, see Errors.

Known specifics

  • The original key is still required. Issuing another key to the same owner does not transfer the request. Even a key with the vibe:cowork scope can check and cancel its own request if the other current checks pass; this does not authorize it to perform infra write operations.
  • Reading detects an outdated request. A status check may return STALE or EXPIRED. That consent cannot be used; create a new request through the original operation.
  • The report does not return secrets. Only the original operation receives Bearer/JWT credentials or secret URLs after application, not these methods.

See also