View as Markdown

Authorities

A custodian authority represents the lifecycle of granting Aleta access to a custodian on behalf of a legal entity.

The GET endpoints on this page need the scope custody:read; the POST endpoints (create, upload, consent, link and revoke) need custody:write. A token without the scope gets 403 Forbidden.

Data model

JSON:API resource type: custodian-authority.

statusstring, required

Current status in the custodian authority lifecycle. One of:

  • waiting-for-files — The custodian authority has been created. Required files (listed in pendingFiles) must be uploaded via POST /custodian-authorities/:id/files.
  • waiting-for-consent — All required files have been uploaded. The consent must now be submitted via POST /custodian-authorities/:id/consent.
  • awaiting-aleta — Consent has been submitted (or the custodian has responded). Aleta is reviewing / processing.
  • awaiting-custodian — Aleta has forwarded the request to the custodian. Waiting for the custodian to act. The status may alternate between awaiting-aleta and awaiting-custodian multiple times.
  • active — The custodian authority is fully established and dataflow is operational.
  • revoke-in-progress — A revocation has been requested. Aleta is removing dataflow links with the custodian.
  • revoked — The custodian authority has been fully revoked. Dataflow has stopped.
  • cancelled — The custodian authority was cancelled before becoming active (e.g. rejected by the custodian).
pendingFilesarray, required

List of file names that still need to be uploaded before consent can be submitted. Only populated when status is waiting-for-files. Empty array otherwise. File names correspond to those defined in the custodian auth flow's expectedFiles.

linkedDepositoriesarray, required

Depositories linked to this custodian authority. Each entry contains:

  • depositoryNumber (string): The depository number.
  • depositoryId (string, nullable): The Aleta depository ID. null for a number added by a specific consent that has not been linked to a depository yet. A depository added with the link endpoint carries its ID from the start.
  • status (string): Status of the linked depository, e.g. in-progress (added by a consent or by the link endpoint; Aleta is setting up the dataflow connection with the custodian) or active.
linkedAccountsarray, required

Accounts linked to this custodian authority. Each entry contains:

  • accountNumber (string): The account number.
  • accountId (string, nullable): The Aleta account ID. null for a number added by a specific consent that has not been linked to an account yet. An account added with the link endpoint carries its ID from the start.
  • status (string): Status of the linked account, e.g. in-progress (added by a consent or by the link endpoint; Aleta is setting up the dataflow connection with the custodian) or active.

Relationships

custodiancustodian

The custodian that the authority relates to.

custodianAuthFlowcustodian-auth-flow

The custodian auth flow used to create the authority.

legalEntitylegal-entity

The legal entity that the authority is granted for.

Custodian authority file

A file uploaded for a custodian authority. Files serve as proof of access. There is no endpoint to delete a file; uploading a file with the same name again replaces the earlier one. JSON:API resource type: custodian-authority-file.

hashstring

SHA-256 hash of the file content in lowercase hex, prefixed with sha2-256: (e.g. sha2-256:7d865e...).

namestring

Logical name identifying the role of the file (e.g. power-of-attorney, consent). Matches one of the custodian auth flow's expectedFiles.

uploadedAtstring, ISO 8601

UTC timestamp of when the file was uploaded, with seven fractional digits and an explicit offset (e.g. 2026-03-01T10:00:00.1234560+00:00).

filenamestring

Original filename as provided by the uploader.

GET/api/v3/legal-entities/{legalEntityId}/custodian-authorities

List a legal entity's authorities

List all custodian authorities for a given legal entity. The response is not paginated.

Parameters

legalEntityIdpath, required

Identifier for the legal entity.

Errors

  • 403 Forbidden — Returned when you do not have read access to the legal entity.
  • 404 Not Found — Returned when the legal entity does not exist.
Request
GET/api/v3/legal-entities/{legalEntityId}/custodian-authorities
GET /api/v3/legal-entities/67b01234a5bc678d90e12345/custodian-authorities HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (200 OK)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "2668e473-b2a2-47a9-a90b-a5ec0c812d44",
      "type": "custodian-authority",
      "attributes": {
        "status": "active",
        "pendingFiles": [],
        "linkedDepositories": [
          {
            "depositoryNumber": "1234-5678901234",
            "depositoryId": "67c01234a5bc678d90e12345",
            "status": "active"
          },
          {
            "depositoryNumber": "1234-5678901235",
            "depositoryId": null,
            "status": "in-progress"
          }
        ],
        "linkedAccounts": [
          {
            "accountNumber": "1234-0011223344",
            "accountId": "67c01234a5bc678d90e12346",
            "status": "active"
          }
        ]
      },
      "relationships": {
        "custodian": {
          "data": {
            "type": "custodian",
            "id": "678e9012f3ab456c78d90123"
          }
        },
        "custodianAuthFlow": {
          "data": {
            "type": "custodian-auth-flow",
            "id": "nordea-20260630"
          }
        },
        "legalEntity": {
          "data": {
            "type": "legal-entity",
            "id": "67b01234a5bc678d90e12345"
          }
        }
      }
    },
    {
      "id": "ac8fa31f-b9bd-414c-a56d-8d95848ebbcf",
      "type": "custodian-authority",
      "attributes": {
        "status": "waiting-for-files",
        "pendingFiles": [
          "power-of-attorney",
          "consent"
        ],
        "linkedDepositories": [],
        "linkedAccounts": []
      },
      "relationships": {
        "custodian": {
          "data": {
            "type": "custodian",
            "id": "679a2345b6cd789e01f23456"
          }
        },
        "custodianAuthFlow": {
          "data": {
            "type": "custodian-auth-flow",
            "id": "saxo-20260630"
          }
        },
        "legalEntity": {
          "data": {
            "type": "legal-entity",
            "id": "67b01234a5bc678d90e12345"
          }
        }
      }
    }
  ]
}
POST/api/v3/legal-entities/{legalEntityId}/custodian-authorities

Create an authority

Create a custodian authority for a given legal entity using the specified custodian auth flow. The new custodian authority is created in the waiting-for-files status. Upload the required files (listed in pendingFiles) using the POST /custodian-authorities/:id/files endpoint to advance to waiting-for-consent.

Parameters

legalEntityIdpath, required

Identifier for the legal entity.

custodianAuthFlowIdquery, required

The custodian auth flow identifier.

Errors

  • 400 Bad Request — Returned when custodianAuthFlowId is missing or empty.
  • 400 Bad Request — Returned when the custodian auth flow ID is outdated. Use the latest custodian auth flow for onboarding.
  • 403 Forbidden — Returned when you do not have write access to the legal entity.
  • 404 Not Found — Returned when the custodian auth flow ID or legal entity ID does not exist.
Request
POST/api/v3/legal-entities/{legalEntityId}/custodian-authorities
POST /api/v3/legal-entities/67b01234a5bc678d90e12345/custodian-authorities
  ?custodianAuthFlowId=nordea-20260630 HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (201 Created)
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "2668e473-b2a2-47a9-a90b-a5ec0c812d44",
    "type": "custodian-authority",
    "attributes": {
      "status": "waiting-for-files",
      "pendingFiles": [
        "power-of-attorney",
        "consent"
      ],
      "linkedDepositories": [],
      "linkedAccounts": []
    },
    "relationships": {
      "custodian": {
        "data": {
          "type": "custodian",
          "id": "678e9012f3ab456c78d90123"
        }
      },
      "custodianAuthFlow": {
        "data": {
          "type": "custodian-auth-flow",
          "id": "nordea-20260630"
        }
      },
      "legalEntity": {
        "data": {
          "type": "legal-entity",
          "id": "67b01234a5bc678d90e12345"
        }
      }
    }
  }
}
GET/api/v3/custodian-authorities/{id}

Retrieve an authority

Get a custodian authority by its id.

Parameters

idpath, required

Custodian authority identifier (a UUID).

Errors

These errors apply to every /api/v3/custodian-authorities/{id} endpoint on this page.

  • 400 Bad Request — Returned when id is not a UUID.
  • 403 Forbidden — Returned when you do not have access to the authority's legal entity (read access for GET, write access for POST).
  • 404 Not Found — Returned when the custodian authority, or its legal entity, does not exist.
Request
GET/api/v3/custodian-authorities/{id}
GET /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44 HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (200 OK)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "2668e473-b2a2-47a9-a90b-a5ec0c812d44",
    "type": "custodian-authority",
    "attributes": {
      "status": "active",
      "pendingFiles": [],
      "linkedDepositories": [
        {
          "depositoryNumber": "1234-5678901234",
          "depositoryId": "67c01234a5bc678d90e12345",
          "status": "active"
        }
      ],
      "linkedAccounts": [
        {
          "accountNumber": "1234-0011223344",
          "accountId": "67c01234a5bc678d90e12346",
          "status": "active"
        }
      ]
    },
    "relationships": {
      "custodian": {
        "data": {
          "type": "custodian",
          "id": "678e9012f3ab456c78d90123"
        }
      },
      "custodianAuthFlow": {
        "data": {
          "type": "custodian-auth-flow",
          "id": "nordea-20260630"
        }
      },
      "legalEntity": {
        "data": {
          "type": "legal-entity",
          "id": "67b01234a5bc678d90e12345"
        }
      }
    }
  }
}
POST/api/v3/custodian-authorities/{id}/files

Upload a file

Upload a file for a custodian authority. The file name is specified via the name query parameter. Supported names are defined by the custodian auth flow (e.g. power-of-attorney, consent, back-office-login).

The returned hash is the SHA-256 of the content, prefixed with sha2-256:.

Once all required files have been uploaded, the custodian authority status transitions from waiting-for-files to waiting-for-consent and pendingFiles becomes empty. Uploading a name that was already uploaded replaces the earlier file of that name.

Parameters

idpath, required

Custodian authority identifier.

namequery, required

Name of the file (e.g. power-of-attorney, consent, back-office-login). Must match one of the names defined in the custodian auth flow's expectedFiles.

Request body

The request body must be multipart/form-data (with a boundary) containing exactly one file part, e.g. a file field. The part's filename is returned as filename.

Errors

  • 400 Bad Request — Returned when name is missing, when the Content-Type is not multipart with a boundary, when the body has no file part or more than one, or when name is not one of the authority's expected files.
Request
POST/api/v3/custodian-authorities/{id}/files
POST /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44/files
  ?name=power-of-attorney HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <access token>
Content-Type: multipart/form-data; boundary=----FormBoundary
Host: api.aleta.ai

------FormBoundary
Content-Disposition: form-data; name="file"; filename="poa_nordea_2026.pdf"
Content-Type: application/pdf

<binary file content>
------FormBoundary--
Response (201 Created)
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "custodian-authority-file",
    "attributes": {
      "hash": "sha2-256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730",
      "name": "power-of-attorney",
      "uploadedAt": "2026-03-01T10:00:00.1234560+00:00",
      "filename": "poa_nordea_2026.pdf"
    }
  }
}
GET/api/v3/custodian-authorities/{id}/files

List files

List all files uploaded for a custodian authority, including their name, hash, upload timestamp, and original filename, oldest upload first. Files serve as proof of access; there is no endpoint to delete one.

Parameters

idpath, required

Custodian authority identifier.

Request
GET/api/v3/custodian-authorities/{id}/files
GET /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44/files HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (200 OK)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "custodian-authority-file",
      "attributes": {
        "hash": "sha2-256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730",
        "name": "power-of-attorney",
        "uploadedAt": "2026-03-01T10:00:00.1234560+00:00",
        "filename": "poa_nordea_2026.pdf"
      }
    },
    {
      "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
      "type": "custodian-authority-file",
      "attributes": {
        "hash": "sha2-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "name": "consent",
        "uploadedAt": "2026-03-01T10:01:00.6543210+00:00",
        "filename": "consent_nordea_2026.pdf"
      }
    }
  ]
}
POST/api/v3/custodian-authorities/{id}/consent

Submit the consent

Submit the consent details. The custodian authority must be in waiting-for-consent status (i.e. all required files have been uploaded). On success, the status transitions to awaiting-aleta.

Parameters

idpath, required

Custodian authority identifier.

Request body

The request body must be a JSON:API document whose data object contains the consent details:

legalEntityIdentifierstring, required

Identifier of the legal entity (e.g. CVR, CPR).

custodianIdentifierstring, required

The identifier attribute from the custodian object.

consentTypestring, required

Type of consent. Possible values (lowercase): "all", "specific".

depositoryNumbersarray of strings, optional

List of depository numbers. Must be empty or omitted when consentType is "all". With "specific", at least one depository or account number is required. Entries must not be empty.

accountNumbersarray of strings, optional

List of account numbers. Same rules as depositoryNumbers.

With consent type specific, the numbers are added to linkedDepositories and linkedAccounts with status in-progress and a null ID.

Errors

  • 400 Bad Request — The body is not valid JSON, has no data object, a field has the wrong type, legalEntityIdentifier or custodianIdentifier is empty, consentType is not all or specific, or the numbers do not match the consent type.
  • 400 Bad Request — The custodian authority is not in waiting-for-consent status.
  • 400 Bad Request — Duplicate all consent. A consent of type all is rejected when another custodian authority for the same legal entity and custodian already has a consent of any type.
  • 400 Bad Request — Overlapping specific consent. For consent type specific, multiple custodian authorities are allowed per legal entity and custodian combination, but not when one of them has consent type all, and the depository numbers and account numbers must not overlap with those linked to any of them.
Request
POST/api/v3/custodian-authorities/{id}/consent
POST /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44/consent HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/vnd.api+json
Host: api.aleta.ai

{
  "data": {
    "legalEntityIdentifier": "12345678",
    "custodianIdentifier": "nordea-dk",
    "consentType": "specific",
    "depositoryNumbers": ["2345-6789012345", "2345-6789012346"],
    "accountNumbers": ["2345-0011223344", "2345-0011223345"]
  }
}
Response (204 No Content)
HTTP/1.1 204 No Content
Response (400 Bad Request)
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": 400,
      "detail": "A custodian authority with consent type 'all' already exists for this legal entity and custodian."
    }
  ]
}
POST/api/v3/custodian-authorities/{id}/link

Link a depository or account

Link a depository or account to a custodian authority. The link is added to linkedDepositories or linkedAccounts with status in-progress, with resourceNumber as both its number and its ID. The authority's status and consent type do not matter and do not change.

Parameters

idpath, required

Custodian authority identifier.

typequery, required

The type of resource to link. Possible values (lowercase): "depository", "account".

resourceNumberquery, required

The Aleta ID of the depository or account to link (the id of the depository or account resource), not the custodian's depository or account number.

Errors

  • 400 Bad Request — Returned when type or resourceNumber is missing, when type is not depository or account, or when the same type and number is already linked to this authority.
  • 500 Internal Server Error — Returned when resourceNumber is not the ID of a depository or account (of that type) you can read, as in the original API.
Request
POST/api/v3/custodian-authorities/{id}/link
POST /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44/link
  ?type=depository
  &resourceNumber=6a62c006959a480cd4000001 HTTP/1.1
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (204 No Content)
HTTP/1.1 204 No Content
POST/api/v3/custodian-authorities/{id}/revoke

Revoke an authority

Request revocation of a custodian authority. The request takes no body.

Returns the custodian authority's ID and its current status. This call does not change the status, whatever status the authority is in, and repeating it returns the same answer; the original API behaves the same way. Use GET /custodian-authorities/:id to read the status.

Parameters

idpath, required

Custodian authority identifier.

Request
POST/api/v3/custodian-authorities/{id}/revoke
POST /api/v3/custodian-authorities/2668e473-b2a2-47a9-a90b-a5ec0c812d44/revoke HTTP/1.1
Authorization: Bearer <access token>
Host: api.aleta.ai
Response (200 OK)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "custodianAuthorityId": "2668e473-b2a2-47a9-a90b-a5ec0c812d44",
    "status": "active"
  }
}