Authorities

A custodian authority is the consent record that lets Aleta pull data from a specific custodian on behalf of a specific legal entity. Authorities are the product of a completed auth flow — they carry whatever tokens, keys, or consent IDs the upstream provider issued, plus the platform's handle for refreshing or revoking them.

Lifecycle

create → link → active ──refresh──▶ active ──revoke──▶ revoked
                │
                └── expire ──▶ expired
  • Create an authority to reserve a slot — no consent yet, but the ID exists so the client app can pass it through an OAuth redirect round-trip.
  • Link the authority once the user completes the upstream consent. This is where the authority transitions to active.
  • Refresh extends the validity window. Required before the custodian's retention ceiling lapses; Aleta pre-emptively refreshes when the provider supports silent renewal.
  • Revoke terminates the consent both at Aleta and upstream (best-effort — not every custodian honours programmatic revocation).

Data model

  • Name
    id
    Type
    string
    Description

    Stable UUID for the authority.

  • Name
    legal_entity_id
    Type
    string
    Description

    The legal entity this authority is granted for.

  • Name
    custodian_id
    Type
    string
    Description

    The custodian the authority authorises against.

  • Name
    auth_flow_id
    Type
    string
    Description

    Which flow produced this authority. Determines what refresh / revoke semantics are available.

  • Name
    status
    Type
    enum
    Description

    pending, active, expired, revoked. The status machine described above.

  • Name
    expires_at
    Type
    timestamp | null
    Description

    When the current consent lapses. Null for flows with no ceiling.

GET/v2/legal-entities/{id}/custodian-authorities

Returns every authority granted for the legal entity, active or otherwise. Useful for rendering the consent management page where admins can see what's linked, what's expiring, and what needs attention.

Request

GET
/v2/legal-entities/{id}/custodian-authorities
curl https://api.aleta.io/v2/legal-entities/{legal_entity_id}/custodian-authorities \
  -H "Authorization: Bearer {token}"
POST/v2/legal-entities/{id}/custodian-authorities

Create a pending authority

Reserves an authority slot before the upstream consent is granted. The returned id is what you pass through the OAuth redirect round-trip so the subsequent link call knows which reservation to fulfil.

Request

POST
/v2/legal-entities/{id}/custodian-authorities
curl -X POST \
  https://api.aleta.io/v2/legal-entities/{legal_entity_id}/custodian-authorities \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "custodian_id": "nordea", "auth_flow_id": "nordea-20260630" }'
POST/v2/custodian-authorities/{id}/link

Completes the consent cycle — called after the user finishes the upstream OAuth flow. Transitions the authority to active and kicks off the first data ingestion.

Request

POST
/v2/custodian-authorities/{id}/link
curl -X POST \
  https://api.aleta.io/v2/custodian-authorities/{id}/link \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "consent_reference": "..." }'
POST/v2/custodian-authorities/{id}/revoke

Revoke an authority

Tears down the consent both at Aleta and, on a best-effort basis, at the custodian. Idempotent — revoking an already-revoked authority returns the same response without changing state.

Request

POST
/v2/custodian-authorities/{id}/revoke
curl -X POST \
  https://api.aleta.io/v2/custodian-authorities/{id}/revoke \
  -H "Authorization: Bearer {token}"
  • Auth flows — the procedures authorities are produced by.
  • Legal entities — authorities are always scoped to a single legal entity.