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

Check an access change request

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

Checks the state of your own access change request before retrying the original operation.

Use the original API key that created the request. Another key belonging to the same owner cannot access it.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionServer ID from the original operation. See List servers
ParameterproposalId Inpath Typestring (UUID) Requiredyes DescriptionRequest ID from error.details.proposalId in a 409 AUDIENCE_APPROVAL_REQUIRED response to changing the policy or minting a token

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/audience-proposals/PROPOSAL_ID" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

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

JavaScript — OAuth application

javascript 
const response = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/audience-proposals/${proposalId}`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)
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 operation under review, the original, proposed and current access snapshots, participant labels and the differences between them.

Field Type Description
Fieldproposal.id Typestring (UUID) DescriptionRequest ID
Fieldproposal.state Typestring DescriptionPENDING, APPROVED, APPLIED, REJECTED, CANCELLED, EXPIRED or STALE
Fieldproposal.baseRevision Typestring DescriptionAccess revision when the request was created; a decimal string
Fieldproposal.currentRevision Typestring DescriptionCurrent access revision; a decimal string
Fieldproposal.expiresAt Typestring DescriptionRequest expiry in ISO 8601
Fieldproposal.canDecide Typeboolean DescriptionAlways false for an API key
Fieldproposal.canCancel Typeboolean DescriptionWhether the request can be cancelled now
Fieldproposal.resultEntityId Typestring (UUID), optional DescriptionID of the record created when applied; not a token or secret URL

Response example

The ID, state and revisions are shown. Other fields are described above.

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

Error response example

404 — server not found:

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

Errors

HTTP Code Description
HTTP400 CodeVALIDATION_ERROR DescriptionInvalid UUID
HTTP401 CodeMISSING_API_KEY DescriptionNo key was supplied
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not recognized
HTTP403 CodePORTAL_COLLABORATOR_NOT_A_MEMBER DescriptionThe collaborator key was revoked or expired, or their portal membership ended
HTTP403 CodeAUDIENCE_APPROVAL_FORBIDDEN DescriptionThe current key, its owner or portal binding no longer permits the operation
HTTP404 CodeNOT_FOUND DescriptionThe server is missing, deleted or not bound to the portal. Message: Server not found
HTTP404 CodeNOT_FOUND DescriptionThe request is missing for this server and portal, or was created by another caller. Message: Proposal not found

For common API errors, see Errors.

Known limitations

  • Approval and application are separate steps. An API key cannot approve a request. Once a person approves it, the APPROVED state lets you retry the original operation with the same key, exact parameters and approvalId.
  • Reading detects an outdated request. A check can return STALE or EXPIRED. Create a new request through the original operation.
  • The original operation returns secrets. Tokens and secret URLs are returned by the original operation after application, not by this check.

See also