## 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 |
|-----------|----|------|:--------:|-------------|
| `id` | path | string (UUID) | yes | Server ID from the original operation. See [List servers](/docs/infra/servers/list) |
| `proposalId` | path | string (UUID) | yes | Request ID from `error.details.proposalId` in a `409 AUDIENCE_APPROVAL_REQUIRED` response to [changing the policy](./access-policy.md) or [minting a token](/docs/infra/access-tokens/create) |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|-------|------|-------------|
| `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

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 |
|------|------|-------------|
| 400 | `VALIDATION_ERROR` | Invalid UUID |
| 401 | `MISSING_API_KEY` | No key was supplied |
| 401 | `INVALID_API_KEY` | The key was not recognized |
| 403 | `PORTAL_COLLABORATOR_NOT_A_MEMBER` | The collaborator key was revoked or expired, or their portal membership ended |
| 403 | `AUDIENCE_APPROVAL_FORBIDDEN` | The current key, its owner or portal binding no longer permits the operation |
| 404 | `NOT_FOUND` | The server is missing, deleted or not bound to the portal. Message: `Server not found` |
| 404 | `NOT_FOUND` | The request is missing for this server and portal, or was created by another caller. Message: `Proposal not found` |

For common API errors, see [Errors](/docs/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

- [Approving wider access](/docs/infra/access#approving-wider-access)
- [Cancel an access request](./audience-proposals-cancel.md)
- [Access policy](./access-policy.md)
- [Mint an access token](/docs/infra/access-tokens/create)