Skip to main content

File Storage

A File Storage holds arbitrary files — as opposed to a Data Storage's structured, searchable JSON, or the small key-value pairs of a User Token. It's a good fit for anything you'd otherwise store as a file: generated PDFs, uploaded attachments, exported data, and similar.

Creating a File Storage​

curl -X POST "https://{your-id-server}/api/rest/v1/filestorage" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signed contracts"
  }'

Requires the FILE_STORAGE_CREATE permission. Every File Storage has an owning User, given as ownerId, which defaults to the caller if not specified; setting a different owner requires the FILE_STORAGE_CREATE_FOR_OTHERS permission and access to that user's namespace. If writeAccess isn't specified, the caller is automatically added to it, so you don't accidentally create a storage nobody (including you) can write to.

Access control​

A File Storage has two independent levels of access:

  • readAccess and writeAccess on the File Storage itself grant access to the storage's metadata and to every file inside it.
  • fileAccessRules grants access to specific files by path, without exposing the rest of the storage or its file listing.

Both are arrays of subjects, each with a type (USER, GROUP, API_CLIENT, OAUTH2_APP, AUTHENTICATED — any signed-in user, or ANONYMOUS — anyone) and, where applicable, an id:

{
    "readAccess": [
        { "type": "GROUP", "id": "{groupId}" }
    ],
    "writeAccess": [
        { "type": "USER", "id": "{userId}" }
    ]
}

Uploading and downloading files​

Files are uploaded as multipart/form-data, with the file's storage path and content as separate parts:

curl -X POST "https://{your-id-server}/api/rest/v1/filestorage/{fileStorageId}/file" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "path=contracts/2026/acme-corp.pdf" \
  -F "[email protected]"

Uploading to a path that already has a file there replaces it. Downloading is a plain GET:

curl "https://{your-id-server}/api/rest/v1/filestorage/{fileStorageId}/file/download?path=contracts/2026/acme-corp.pdf" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -o acme-corp.pdf

Both require write access (to upload or delete) or read access (to download) — either to the whole File Storage, or to that specific path via fileAccessRules.

Last updated on