Management API

The Python service publishes versioned /v1 routes for people, Institutions, projects, approval workflows, lifecycle, audit, and operations. The generated OpenAPI document below reflects the routes and request schemas published by this source version.

Success response models are declared for own account and freshness; core Institution, person, project, membership and access reads; audit reads and search; the operations summary; lifecycle feed, snapshot and acknowledgement; project catalog and client review; exact Access grant review; and reviewed lifecycle service grants. Other success shapes remain unspecified.

The service URL is private deployment configuration, not a universal public API hostname.

Find the route you need

• Read own account and freshness: GET /v1/me, /v1/me/freshness. Returns an account object, or signed snapshot and receipt.
• Review Institutions and projects: GET /v1/institutions, /v1/projects. Returns arrays scoped to current authorization.
• Inspect project authority: GET /v1/projects/{project_id}/authority-status. Returns bounded source observations for lifecycle acknowledgement, reviewed clients, source grants and activation. A current signed readback may report the Go writer’s observed active state until an exclusive deadline. It does not confirm effective sign-in.
• Request a client environment: /v1/projects/{project_id}/environments. Returns reviewed workflow records.
• Review catalog and owned-client policy: /v1/projects/{project_id}/permission-catalogs, /owned-clients. Returns exact independently reviewed metadata; client approval awaits installation readback.
• Request controlled credential custody: POST /v1/projects/{project_id}/owned-clients/credential-intents. Returns an intent UUID and custody_status: pending; no secret, installation or effectiveness claim.
• Independently review an Access version: /v1/institutions/{institution_id}/access-grant-reviews. Returns candidates, immutable decision receipts and separate current/delivery facts.
• Consume product eligibility: /v1/lifecycle/{project_id} and /snapshot. Returns signed events or snapshot, receipt, cursor.
• Search audit: GET /v1/audit/search. Returns items, next_cursor, limit.
• Diagnose delivery: GET /v1/operations/diagnostics, project diagnostics. Returns queue and acknowledgement state.

The simple GET /v1/audit endpoint returns up to 200 entries. Use /v1/audit/search for filtered cursor pagination: its limit is 1 to 1000, default 100. Pass back the returned next_cursor with the same actor, scope and filters. An invalid cursor returns 400.

Authenticate and mutate

Use a bearer access token with audience taifa-management. Most protected reads additionally require current local eligibility.

For human mutations, send a new Idempotency-Key and an operation-specific JSON body containing an audit reason of 8 to 500 characters. Actual strong authentication must be recent; platform administration needs phishing-resistant assurance.

The server commits the mutation, audit record, idempotency response, and outbox work together. A queued result is not product effectiveness.

Follow completion

Some approved actions require worker delivery or exact product acknowledgement. Distinguish pending, accepted, and effective; do not promise access based on an approval response.

Lifecycle acknowledgements report the applied sequence. Account linking has an additional exact binding acknowledgement. See lifecycle and operations.

Exact grant-review POSTs return immutable decision receipts. Current validity and event acknowledgment are available from the scoped GET, including after an exact idempotency replay.

pending_review intentionally reports current:false. An approved review or client policy does not establish an installed client or effective issuer assignment. Review the typed grant API and reread current facts after every uncertain decision.

Credential intents expire at their original deadline, at most 120 seconds after creation. An exact replay cannot renew an intent or restore revoked authority.

The controlled runtime obtains the signed intent through a separate private machine boundary; that operation is excluded from the public API reference.

See credentials and rotation for the human request and custody rules. Reviewed client installation and production activation remain separate requirements.

Read project authority observations

Use the project authority status operation to inspect one approved project with current owner or project-approver authority. This read requires a Management access token. It does not create or approve authority, and it does not require an idempotency key or a mutation reason.

GET /v1/projects/PROJECT_ID/authority-status?limit=25&offset=0 HTTP/1.1
Authorization: Bearer ACCESS_TOKEN_WITH_TAIFA_MANAGEMENT_AUDIENCE
Accept: application/json

The response separates lifecycle, client policy, stream, historical source_ack, source grant and activation observations. Lifecycle sequences, client versions and generations are decimal strings, preserving the full integer value in JavaScript. Observation and expiry timestamps use Unix seconds.

The top-level activation_effectiveness remains unknown. Each activation’s effectiveness is unknown unless Management has verified the exact historical activation result and a fresh signed positive Go readback against the current source grant and review chain. A positive value is observed_active only until its exclusive observed_active_until timestamp. The original activation expires_at is historical and can precede a later renewal observation. A loaded view downgrades the positive display at the deadline; reload the route to detect a source decision or custody change. This writer-local observation does not establish issuer sign-in effectiveness or production release. An unexpired source record, historical ACK or pending activation alone must not enable sign-in or product access.

Collection reads accept limit from 1 to 50 (default 25) and offset from 0 to 10000. Follow a non-null next_offset to read another page. Each request observes the current source records; pages are not a frozen snapshot. Reread after a review, revocation or renewal changes the collection. The endpoint does not return credentials, machine nonces, private signed payloads or beneficiary identities.

If a next page would exceed the offset bound, the route returns 409 with detail: "pagination_limit_reached". It does not report the truncated list as complete. Handle that refusal explicitly rather than treating it as an empty page.

If the route returns 403, check the current project scope rather than trusting an old role claim. A 404 means an approved project was not available. Handle an unavailable response as an unconfirmed observation, not a clean or effective state. Verify the deployed API version before using this source addition.

Errors and versioning

Error responses use FastAPI’s detail shape, with X-Request-ID on responses. A 409 can mean changed state or an idempotency conflict. A 503 can mean required authentication, audit, signing, or delivery dependencies are unavailable.

Handle unknown optional fields and read the downloadable OpenAPI JSON at /docs/openapi.json for the deployed source version. Verify the actual deployed API version separately before using a newly documented route.

Browse the reference

Open the API reference to browse resources, operation pages, declared request and response fields, and cURL, TypeScript, and Python request examples. Download the public OpenAPI JSON for the exact published source contract. Undocumented success shapes are labeled explicitly.

Lifecycle service grants

The source exposes /v1/projects/{project_id}/lifecycle-service-grants for three decisions:

1. A current owner proposes a grant with issuer, subject, and reason.

2. An independent platform reviewer approves it at /{grant_id}/approve with expected_version, proposal_digest, and reason.

3. A current scoped owner or platform reviewer terminally revokes it at /{grant_id}/revoke with the current expected_version and reason.

Human decisions require Idempotency-Key and a trimmed 8..500-character reason. GET returns scoped grant metadata and accepted Audit references, never credentials. Collection reads use limit (1..100, default 50) and optional after_id.

Pending review is version 1; local effective authority is version 2. Revocation increments the version and cannot reactivate. Attestor grants do not authorize feed, snapshot or ACK, and machine requests require exactly the lifecycle role plus current exact-purpose grant.

Grant approval is neither token issuance nor client installation. Owned issuer client-credentials issuance remains unimplemented; verify the deployed API before using newly documented routes.