Custodian authorities

A custodian authority is the power of attorney that lets Aleta pull an entity's data from a bank. You open one on the bank's auth flow, upload the files the bank asks for, give consent, and Aleta sets it active once data runs. Linking tells Aleta which of the entity's cash and custody accounts the authority covers.

Reads need custody:read, writes custody:write. Every write takes ?dry_run=true (validates and answers without saving, with the header Aleta-Dry-Run: true) and an Idempotency-Key header (the same key and body answer the first result again; the same key with another body is 409), and is logged in the change list.

Lifecycle

status	meaning	moves on by
`waiting_for_files`	The bank's flow expects files that are not uploaded yet.	Uploading the last expected file, or consent (files are optional).
`waiting_for_consent`	Nothing pending: a flow without files (a netbank flow, e.g. Jyske Bank or Nykredit) starts here.	Consent.
`awaiting_aleta`	The client consented; Aleta sets the authority up with the bank. Aleta is notified by the event `custodian_authority.awaiting_aleta` on `GET /v1/events`.	Aleta's activate.
`awaiting_custodian`	Only on authorities from the legacy platform that carry it.	Aleta's activate.
`active`	Data runs. Only Aleta sets it.	Revoke.
`revoke_in_progress`	Revoking started (closing the client starts it) and Aleta still has to confirm it at the bank. No files, consent or links meanwhile.	Aleta's revoke.
`revoked`	Ended. Every link is `revoked`.	—
`cancelled`	Revoked while not `active` and with no linked account.	—

Linking never changes the status. Revoking or cancelling ends the authority; a second revoke answers it unchanged. revoked means the links are marked revoked; it does not stop data loading. The bank's files keep arriving until Aleta ends the feed with the bank.

Every 409 names its rule in code, with next_action when there is a way out:

code	when	`next_action`
`consent_required`	A link before consent on an authority that is not active.	`POST /v1/custodian-authorities/{id}/consent`
`not_consented`	A link of a number the `specific` consent does not cover.	—
`invalid_status`	Consent in `awaiting_aleta`, `awaiting_custodian` or `active`.	—
`consent_conflict`	`all` while a `specific` authority exists for the same entity and bank.	—
`consent_overlap`	A `specific` number another authority already covers.	—
`revoke_in_progress`	Files, consent, link or activate while Aleta finishes a revoke.	ask Aleta (`GET` the authority)
`authority_closed`	Files, consent, link or activate on a revoked or cancelled authority.	—
`flow_outdated`	Opening an authority on an outdated flow.	`GET /v1/custodian-auth-flows?custodian_id=…&status=active`
`concurrent_change`	Another write changed the authority meanwhile: retry.	—

The authority

idstring: Stable identifier. A UUID.
entity_idstring: The entity the authority is for.
custodian_idstring or null: The bank, as in custodians.
custodian_auth_flow_idstring: The bank's auth flow the authority was opened on.
statusstring: See the lifecycle above.
consent_typestring or null: all (every account of the entity at the bank) or specific (the numbers given), once consented.
pending_filesstring[]: The expected files not uploaded yet.
linked_resourcesobject[]: {kind, number, resource_id, status}: kind is cash_account or custody_account, number the bank's number, resource_id the cash or custody account once linked (null before), status in_progress (consented number, not linked yet), linked or revoked. number and status may be null.
created_by_user_idstring or null: Who opened the authority; null on authorities from the legacy platform.
created_at, updated_atstring: ISO 8601 timestamps.

GET/v1/custodian-authorities

List authorities

The authorities on the entities you see, oldest first, one page at a time (limit, cursor). Any other query parameter is 400.

Optional attributes

entity_idstring: Only this entity's.
custodian_idstring: Only this bank's.
statusstring: One status from the lifecycle (snake_case; any other value is 400).

Response

{
  "data": [
    {
      "id": "0199f2a0-7c1e-7a40-9d1b-3c5e8f0a2b11",
      "entity_id": "0199f29f-1b2c-7d3e-8f40-5a6b7c8d9e0f",
      "custodian_id": "019dff7d-5a85-741e-8437-22e1d5f7c685",
      "custodian_auth_flow_id": "nykredit-netbank-1",
      "status": "awaiting_aleta",
      "consent_type": "specific",
      "pending_files": [],
      "linked_resources": [
        { "kind": "custody_account", "number": "1234567", "resource_id": null, "status": "in_progress" }
      ],
      "created_by_user_id": "0199f29e-4a5b-7c6d-8e9f-0a1b2c3d4e5f",
      "created_at": "2026-10-18T08:00:00.000000Z",
      "updated_at": "2026-10-18T08:05:00.000000Z"
    }
  ],
  "next_cursor": null,
  "limit": 100
}

GET/v1/custodian-authorities/{id}

Get an authority

One authority, in the shape above. 404 for an unknown id, an id that is not a UUID, and an authority on an entity you do not see.

POST/v1/custodian-authorities

Open an authority

Body {entity_id, custodian_auth_flow_id}. 201 with the authority in waiting_for_files, or waiting_for_consent when the flow expects no files. An unknown entity or flow is 404, an outdated flow 409 flow_outdated, also when the flow is retired while the authority is being opened.

POST/v1/custodian-authorities/{id}/files

Upload a file

Multipart: a name field (one of the flow's expected files) and one file, up to 100 MiB in total. 201 with the file. The last expected file moves waiting_for_files to waiting_for_consent. A missing name or file part and an unexpected name are 400; an authority you do not see 404; a revoked or cancelled authority 409 authority_closed, and one being revoked 409 revoke_in_progress.

The file

idstring: A UUID.
custodian_authority_idstring: The authority.
namestring: The flow's expected file it fills.
filenamestring: The uploaded file's name.
sha256string: The file's SHA-256, lowercase hex.
document_idstring or null: The document the file is filed as; null until it is, or when you cannot see it.
uploaded_atstring: ISO 8601 timestamp.

GET/v1/custodian-authorities/{id}/files

List the files

The authority's uploaded files, oldest first, in the shape above, as {data, next_cursor, limit} in one page: next_cursor is null and limit is the number of files (0 when none is uploaded). An authority you do not see, or an id that is not a UUID, is 404.

POST/v1/custodian-authorities/{id}/consent

Body {consent_type, custody_account_numbers?, cash_account_numbers?}: all without numbers, or specific with at least one. Taken in waiting_for_files (missing files stay pending) and waiting_for_consent; 200 with the authority in awaiting_aleta and the numbers as in_progress links. Consent in any other status is 409, as is all while a specific authority exists for the same entity and bank, or a number another authority covers.

POST/v1/custodian-authorities/{id}/link

Link an account

Body {kind, resource_id} with kind cash_account or custody_account. Attaches one of the entity's own accounts; the status does not change. Under a specific consent only a consented number can be linked (409 not_consented); an authority Aleta activated without consent takes any of the entity's accounts. Before consent (and not active) it is 409 consent_required; an account of another entity 400; an account you do not see 404. A link writes on the account, so your access must cover the whole account (its tenant, client, entity or the account itself), else 403. Linking a linked account again answers 200 unchanged, nothing written or logged.

POST/v1/custodian-authorities/{id}/activate

Activate

Aleta only: the fleet key in the aleta_internal seat (a fleet key for staff support and anyone else get 403). Body {reason?}, which may be left out. Sets the authority active from any status before it, also without files or consent, once data runs. An active authority answers 200 unchanged and nothing is logged; revoke_in_progress, revoked and cancelled are 409.

POST/v1/custodian-authorities/{id}/revoke

Revoke

Body {} or none. Ends the authority: revoked, or cancelled when it is not active and has no linked account. Every link is marked revoked. A revoked or cancelled authority answers 200 unchanged. A revoke_in_progress authority is Aleta's to finish once the bank confirms: Aleta's revoke (the fleet key in the aleta_internal seat) ends it, anyone else gets it back 200 unchanged.