# Custodian authority (single)

A custodian authority represents the lifecycle of granting Aleta
access to a custodian on behalf of a legal entity. The lifecycle
moves through several statuses depending on file uploads, consent,
custodian responses, and revocation.

## Lifecycle / status values

  waiting-for-files    — The authority has been created. The files in
                         `pendingFiles` must be uploaded via
                         POST /v2/custodian-authorities/:id/files.
  waiting-for-consent  — All files uploaded. A signed consent JWT
                         must now be submitted via
                         POST /v2/custodian-authorities/:id/consent.
  awaiting-aleta       — Consent submitted. Aleta is reviewing.
  awaiting-custodian   — Aleta has forwarded to the custodian. May
                         alternate with awaiting-aleta multiple times.
  active               — Fully established and dataflow is operational.
  revoke-in-progress   — Revocation requested. Aleta is removing dataflow.
  revoked              — Fully revoked. Dataflow has stopped.
  cancelled            — Cancelled before becoming active (e.g. rejected by the custodian).

## Endpoints

GET /v2/custodian-authorities/:id
  Fetch one custodian authority.

GET /v2/custodian-authorities/:id/files
POST /v2/custodian-authorities/:id/files
  Manage proof-of-access files. Files cannot be deleted.

POST /v2/custodian-authorities/:id/consent
  Submit a signed consent JWT after all files have been uploaded.

POST /v2/custodian-authorities/:id/link
  Link an additional account or depository to the authority.

POST /v2/custodian-authorities/:id/revoke
  Request revocation of the authority.

GET /v2/legal-entities/:id/custodian-authorities
POST /v2/legal-entities/:id/custodian-authorities
  Listing / creation under a legal entity. See
  `aleta api --spec /v2/legal-entities/:id/custodian-authorities`.

## Path params

  id (required) — Custodian-authority identifier (UUID).

## Attributes (`type: custodian-authority`)

  status              (string) — see lifecycle above.
  pendingFiles        (array of string) — file names still required
                       (matches `expectedFiles` on the auth flow).
  linkedDepositories  (array of {depositoryNumber, depositoryId, status})
  linkedAccounts      (array of {accountNumber,    accountId,    status})

## Relationships

  custodian          — The custodian the authority relates to.
  custodianAuthFlow  — The auth flow used to create it.
  legalEntity        — The legal entity the authority is granted for.