Eligibility and lifecycle

An application must keep its local workforce access aligned with management’s ordered signed feed. The feed contract is implemented by the Python service, while production product adapters and owned-issuer provisioning still need acceptance.

Reviewed machine authority

The current source requires an active, independently reviewed lifecycle-consumer grant bound to the exact signed issuer, subject and project.

A role claim or account-link attestor grant is insufficient. Mixed machine roles are refused.

A current project owner proposes the grant; a different platform project-approver reviews its exact version and digest. Local grant approval creates neither a client nor tokens. Owned issuer client-credentials issuance and live product provisioning remain separate acceptance gates. Verify the deployed API version before relying on these routes.

A current scoped owner or platform reviewer can revoke the grant. Revocation is terminal: pending or effective grants cannot reactivate through an old receipt.

When revocation commits before a waiting acknowledgement, that request is denied without advancing the project cursor. An already committed acknowledgement stays committed. Multiple credentials for one project share one logical consumer cursor, not independent proof that separate products applied changes.

Poll and apply

1. Call GET /v1/lifecycle/{project_id}?after=CURSOR every 15 seconds using a dedicated project-scoped service access token. The response contains up to 500 signed events, a signed receipt, next_cursor, and has_more.

2. Verify the dedicated RS256 lifecycle key ID, signature, issuer, audience, kind, sequence, and receipt expiry. This key is separate from the issuer’s OIDC JWKS. A gap, wrong project, stale version, or invalid signature must close protected access until catch-up.

3. Apply entity changes and advance your durable cursor in one database transaction. Duplicate events are safe. Send POST /v1/lifecycle/{project_id}/ack with {"sequence": APPLIED_CURSOR} only after the durable commit. The sequence is a strict integer from 0 to 2147483647. Equal-cursor retry is harmless; decreasing or above-head values are refused.

If the cursor is invalid or history is missing, request GET /v1/lifecycle/{project_id}/snapshot.

Verify the signed head and entities, rebuild safely, then resume the feed. Snapshot recovery currently refuses more than 5000 entities or 2 MiB of serialized entity data with 503, without signed truncation. Larger cohorts need an accepted recovery path; do not treat that refusal as a fresh receipt.

Enforce freshness

A signed receipt is valid for at most 60 seconds. Accept it only after applying all changes through its head. Protected workforce requests fail closed when that window expires. A service outage can leave access open only for the remaining valid receipt interval.

Public documentation and unrelated anonymous routes can remain available.

For revoked access, end local refresh sessions and protected real-time connections.

A product’s acknowledgement is required before central operations report effective delivery. Do not treat the existence of a queued outbox item as effective revocation.

Independently review an exact grant

A current Access record and an acknowledged lifecycle Event do not independently authorize an owned-issuer assignment. Historical requests without the decision evidence below need a new reviewed path.

1. An actual Institution Sponsor proposes the exact Access ID/version through POST /v1/institutions/{institution_id}/access-grant-reviews.

2. A different effective Institution administrator approves the resulting review through /{review_id}/approve. Both reviewers must differ from the beneficiary.

Read GET /v1/institutions/{institution_id}/access-grant-reviews to inspect candidates, immutable review bindings and current facts.

The portal exposes this workflow at /organizations/{institution_id}/access; sponsor-only access does not permit the other administrator areas.

Inspect the beneficiary issuer/subject, Person and Membership versions, exact project/Event, reviewer generations, fingerprints and accepted Audit bindings.

Proposals contain only access_id, access_version and reason; approval and review revocation contain only reason. Every decision needs recent strong authentication and a target-bound Idempotency-Key.

POST returns an immutable receipt. Preserve the same exact body and key after response loss, then reread the scoped GET.

pending_review has current:false until independent approval. An approved receipt does not guarantee that its review is still current.

delivery_acknowledged:true requires the exact grant Event to be acknowledged and the project head to match the applied cursor. Reviewed client installation, signed assignment and product-local roles remain separate gates. Revoking a review retains its evidence and does not mutate the underlying Access record.

Browse the exact grant-review API for declared requests, response fields and examples.

Personal portal state

GET /v1/me/freshness returns a signed personal snapshot and receipt for audience taifa-identity-portal. The portal applies only nondecreasing versions and checks the exact issuer and subject. It requests fresh state at most 15 seconds after the previous receipt. The personal route is not a substitute for a product’s project feed.

Test the consumer

The Node example has an in-memory poller and intentionally does not acknowledge a cursor. Run npm test in examples/node to inspect duplicate, gap, expiry, and signature refusal. Before production, replace memory with a durable transaction, test snapshot recovery, and verify real management and product integration.