API reference

Propose independent review of one Access version

Management API contract View .md

A current actual Sponsor proposes the exact active Access version. The accepted receipt records no issuer assignment. Exact idempotency replay returns the original receipt.

POST/v1/institutions/{institution_id}/access-grant-reviews

Authentication Bearer access token with audience taifa-management. Roles and local eligibility are reviewed separately from the OpenAPI bearer scheme.

Parameters

Name	In	Type	Required	Description
`institution_id`	path	`string`	Yes
`idempotency-key`	header	`string`	Yes

Request body

application/jsonRequiredGrantProposal

Field	Type	Required	Description
`reason`	`string`	Yes	Validation: min length 8; max length 500
`access_id`	`string`	Yes	Validation: min length 1; max length 200
`access_version`	`integer`	Yes	Validation: minimum 1; maximum 9223372036854775807

Responses

201Successful Response

Content type: application/jsonGrantReceipt

Field	Type	Required
`id`	`string`	Yes
`status`	`pending_review \| approved \| revoked \| superseded`	Yes
`access_id`	`string`	Yes
`access_version`	`integer`	Yes
`project_id`	`string`	Yes
`beneficiary_person_id`	`string`	Yes
`beneficiary_issuer`	`string`	Yes
`beneficiary_subject`	`string`	Yes
`beneficiary_person_version`	`integer`	Yes
`beneficiary_membership_id`	`string`	Yes
`beneficiary_membership_version`	`integer`	Yes
`event_id`	`string`	Yes
`event_sequence`	`integer`	Yes
`event_digest`	`string`	Yes
`source_request_id`	`string \| null`	Yes
`sponsor_id`	`string`	Yes
`sponsor_generation`	`integer`	Yes
`sponsor_actor`	`string`	Yes
`sponsor_person_id`	`string`	Yes
`sponsor_person_version`	`integer`	Yes
`sponsor_membership_id`	`string`	Yes
`sponsor_membership_version`	`integer`	Yes
`sponsor_fingerprint`	`string`	Yes
`sponsor_audit_id`	`string`	Yes
`sponsor_operation`	`string`	Yes
`sponsor_target`	`string`	Yes
`administrator_proposal_id`	`string \| null`	Yes
`administrator_generation`	`integer \| null`	Yes
`administrator_actor`	`string \| null`	Yes
`administrator_person_id`	`string \| null`	Yes
`administrator_person_version`	`integer \| null`	Yes
`administrator_membership_id`	`string \| null`	Yes
`administrator_membership_version`	`integer \| null`	Yes
`approved_fingerprint`	`string \| null`	Yes
`administrator_audit_id`	`string \| null`	Yes
`administrator_operation`	`string \| null`	Yes
`administrator_target`	`string \| null`	Yes
`created_at`	`string`	Yes
`expires_at`	`string`	Yes

Other responses

Status	Description	Schema
422	Validation Error	`HTTPValidationError`

Request example

Illustrative only. TypeScript runs in Node.js on the server. Keep management tokens out of browser bundles. Replace the host, token, path values, and any header or required body placeholders before use. Examples do not send requests.

curl -X POST 'https://YOUR_IDENTITY_HOST/v1/institutions/REPLACE_WITH_INSTITUTION_ID/access-grant-reviews' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "access_id": "00000000-0000-4000-8000-000000000001",
  "access_version": 1,
  "reason": "Request independent review of current case access"
}'

Response example

{
  "access_id": "00000000-0000-4000-8000-000000000011",
  "access_version": 2,
  "administrator_actor": "https://people.example.test|synthetic-administrator",
  "administrator_audit_id": "00000000-0000-4000-8000-000000000023",
  "administrator_generation": 2,
  "administrator_membership_id": "00000000-0000-4000-8000-000000000022",
  "administrator_membership_version": 1,
  "administrator_operation": "access-grant-review.approve:institution:review",
  "administrator_person_id": "00000000-0000-4000-8000-000000000021",
  "administrator_person_version": 2,
  "administrator_proposal_id": "00000000-0000-4000-8000-000000000020",
  "administrator_target": "00000000-0000-4000-8000-000000000010",
  "approved_fingerprint": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "beneficiary_issuer": "https://people.example.test",
  "beneficiary_membership_id": "00000000-0000-4000-8000-000000000014",
  "beneficiary_membership_version": 1,
  "beneficiary_person_id": "00000000-0000-4000-8000-000000000013",
  "beneficiary_person_version": 1,
  "beneficiary_subject": "synthetic-holder",
  "created_at": "2026-10-04T10:00:00+00:00",
  "event_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "event_id": "00000000-0000-4000-8000-000000000015",
  "event_sequence": 7,
  "expires_at": "2027-01-02T10:00:00+00:00",
  "id": "00000000-0000-4000-8000-000000000010",
  "project_id": "00000000-0000-4000-8000-000000000012",
  "sponsor_actor": "https://people.example.test|synthetic-sponsor",
  "sponsor_audit_id": "00000000-0000-4000-8000-000000000019",
  "sponsor_fingerprint": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "sponsor_generation": 3,
  "sponsor_id": "00000000-0000-4000-8000-000000000016",
  "sponsor_membership_id": "00000000-0000-4000-8000-000000000018",
  "sponsor_membership_version": 2,
  "sponsor_operation": "access-grant-review.propose:institution:access",
  "sponsor_person_id": "00000000-0000-4000-8000-000000000017",
  "sponsor_person_version": 2,
  "sponsor_target": "00000000-0000-4000-8000-000000000010",
  "status": "approved"
}

All Reviewed Access grants operations