Register
API Explorer
https://k8s.openbankproject.com

Files

Files

A File is a document such as a PDF or a photograph, stored in a space: a bank, or SYS for the system space. A file can be attached to records, such as a Customer or a Dynamic Entity record, and can be shared with Users.

A file never changes

A file's content never changes once stored, and OBP keeps its SHA-256. A new version of a document is a new file. What can change is which records the file is attached to, which Users have been given access to it, and whether it is public. Files are not deleted.

Storing a file

Create File takes the file base64 encoded in JSON, with its name and media type. It needs the Role CanCreateFileAtOneBank at the space (granted at SYS for the system space; there is no AtAnyBank version). The caller becomes the file's owner: the User an agent acts for, when one does.

At most these media types are ever accepted: image/jpeg, image/png, image/webp and application/pdf. The prop files.allowed_media_types can narrow that list but never extend it, and the content must really be of the type it claims. The prop files.max_size_in_bytes limits the size (10 MB by default).

Personal files

A person may also store a file in their own name without a Role, through Create My File, for example a pitch deck for an application or a document for a KYC check. Personal files are off unless the space is listed in the prop files.personal.enabled_bank_ids. The owner's email address must be validated (for a User of another identity provider, having one is enough); each User holds a limited number and size of personal files per space (files.personal.max_files_per_user, files.personal.max_total_bytes_per_user, files.personal.max_size_in_bytes); the media types are those of files.personal.allowed_media_types, within the ones the space allows; and a personal file is never public. It is attached at once to one of the owner's own personal Dynamic Entity records, and only such records take it later, unless a holder of CanCreateFileAtOneBank attaches it.

Scan status

Every file has a scan_status: pending, clean or rejected. A personal file starts pending; a file stored with the Role starts clean, as do files stored before scanning existed, except in a bank made with Create My Bank (self-service): anyone can grant themselves Roles there, so every file stored there starts pending. Until a file is clean, its details are shown as usual but its content is served only to its owner and to holders of CanUpdateFileScanStatusAtOneBank; a rejected file's content is not served at all, and only clean files are public. A scanner, holding CanUpdateFileScanStatusAtOneBank as a Scope, lists the waiting files with Get Files of a Space and scan_status=pending, reads them, and sets the result with Update File Scan Status; a member of staff with the Role does the same by hand, to approve a file when no scanner is configured, to reject a reported one, or to clear a false positive.

Who may read a file

A logged-in caller may read a file they own, a file its owner has given them access to, or any file of a space where they hold the Role CanGetFileAtOneBank. Only the owner gives and takes access, and only to a person: a consent user is refused, since access given to one would end with its Consent. Get Files of a Space lists every file of a space for holders of CanGetFileAtOneBank.

Attaching files to records

The owner, or a holder of CanCreateFileAtOneBank, attaches a file to a record and detaches it. A record is named by record_type (e.g. customer, or a Dynamic Entity's name) and record_id, and a file is attached to a record at most once. OBP does not look the record up, so access to a file never follows from access to a record: it comes only from owning the file, being given access to it, or the Role CanGetFileAtOneBank.

These endpoints are UserXORApplication: an application acting as itself, with a client-credentials token, may hold the Roles as Scopes on its Consumer. A person calling through a Consumer still needs their own Entitlements.

Public files

A file can be public, so anyone can read it without logging in. Storing a public file, or making a file public or not later, also needs the Role CanCreatePublicFileAtOneBank. Public files are served by their own endpoints under public-files, which serve nothing that is not public and say nothing of who stored the file. Their content may be cached for an hour, so a withdrawn file may still be served from a cache for that long.

Content

The content endpoints return the file itself, not JSON, with its own Content-Type, its SHA-256 as the ETag, and Content-Disposition naming it (?inline=true to show it in a browser). So that a file can never run as a page of this site, they also send X-Content-Type-Options: nosniff and a sandbox Content-Security-Policy.

Storage

The bytes are kept apart from what is known about the file. Today they are stored in the database; they can be moved to object storage without changing the API.

Endpoints