# 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](/docs/lifecycle) and [operations](/docs/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](/docs/api/groups/reviewed-access-grants) 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](/docs/credentials) 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](/docs/api/operations/project_authority_status)
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.

```http
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](/docs/api) to browse resources, operation pages, declared request and response fields, and cURL, TypeScript, and Python request examples. [Download the public OpenAPI JSON](/docs/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.