Storage Buckets

Overview

Uplint stores every accepted file in your own cloud storage, using credentials you provide. It supports two providers:

Amazon S3 — files are stored as objects in an S3 bucket.
Azure Blob Storage — files are stored as blobs in an Azure container.
Google Cloud Storage — files are stored as objects in a GCS bucket (via GCS’s S3-compatible API).

A storage bucket (also called a storage configuration) bundles the details Uplint needs to read and write on your behalf. Some fields are common to both providers; others are provider-specific:

The provider (aws_s3, azure_blob, or gcs)
The bucket / container name files are written to
A base path prefix applied to every object/blob written
The provider’s credentials (encrypted at rest, never returned)
A human-friendly name used to identify the bucket in the dashboard and API

A tenant can register many buckets — and they can be a mix of providers. One of them is always the default (fallback) bucket, and each file context can be routed to any active bucket you choose. This lets you keep, say, patient documents in S3 and exports in Azure — each with its own credentials, region, and lifecycle — while still driving everything through one Uplint API.

All storage bucket endpoints require an API key with the admin scope. Managing storage is an administrative operation, distinct from the upload/download scopes used for day-to-day file traffic.

Choosing a provider

The provider field selects the backend. It defaults to aws_s3, so existing S3-only integrations keep working unchanged. Each provider needs its own credential fields:

Amazon S3 (aws_s3)
Azure Blob Storage (azure_blob)
Google Cloud Storage (gcs)

Field	Required	Description
`provider`	No	`aws_s3` (the default if omitted).
`access_key_id`	Yes	AWS access key ID.
`secret_access_key`	Yes	AWS secret access key. Encrypted at rest, never returned.
`region`	No	AWS region, e.g. `ap-south-1`. Defaults to `ap-south-1`.
`default_bucket`	Yes	The S3 bucket name.
`base_path`	No	Key prefix for every object. Defaults to `file-service/`.
`name`	Yes	Friendly label, unique per tenant.

Uplint serves downloads with short-lived S3 pre-signed URLs.

Field	Required	Description
`provider`	Yes	`azure_blob`.
`account_name`	Yes	Azure storage account name.
`account_key`	Yes	Azure storage account key (Shared Key). Encrypted at rest, never returned.
`default_bucket`	Yes	The Azure container name.
`endpoint_suffix`	No	Endpoint suffix for sovereign clouds, e.g. `core.usgovcloudapi.net` or `core.chinacloudapi.cn`. Leave blank for public Azure (`core.windows.net`).
`base_path`	No	Blob-name prefix for every file. Defaults to `file-service/`.
`name`	Yes	Friendly label, unique per tenant.

Uplint serves downloads with short-lived blob SAS URLs — the Azure equivalent of S3 pre-signed URLs. Generating them requires the account key, which is why Azure buckets use Shared Key (account name + key) authentication.

GCS is accessed through its S3-interoperable (XML) API using HMAC keys, so the credential fields mirror Amazon S3.

Field	Required	Description
`provider`	Yes	`gcs`.
`access_key_id`	Yes	GCS HMAC access key (starts with `GOOG…`).
`secret_access_key`	Yes	GCS HMAC secret. Encrypted at rest, never returned.
`default_bucket`	Yes	The GCS bucket name.
`base_path`	No	Object-name prefix for every file. Defaults to `file-service/`.
`name`	Yes	Friendly label, unique per tenant.

Create an HMAC key in the Google Cloud console under Cloud Storage → Settings → Interoperability. Uplint talks to storage.googleapis.com and serves downloads with short-lived signed URLs, just like S3. No region is required.

For Azure, the storage account must have “Allow storage account key access” enabled (it is on by default). Without it, Azure rejects the account key and uploads fail with “Key based authentication is not permitted on this storage account.”

Why multiple buckets?

A single bucket works fine when everything you ingest belongs together. Multiple buckets — even across providers — become useful when different kinds of uploads have different requirements:

Data separation

Keep regulated data (e.g. medical claims) in a dedicated bucket, isolated from lower-sensitivity uploads like profile photos.

Data residency

Route EU uploads to an eu-west-1 S3 bucket and APAC uploads to an Azure container in a nearby region to satisfy residency requirements.

Independent credentials

Give each bucket its own IAM key or storage account so you can rotate or revoke access for one workload without touching the others.

Cost & lifecycle

Apply different lifecycle and storage-class/tier policies per bucket, matched to how long each data type must live.

The default bucket

Exactly one bucket is the tenant’s default at any time, regardless of provider. The default is the fallback Uplint uses whenever a more specific bucket can’t be determined — for example, when a file context isn’t bound to a bucket.

The first bucket you add automatically becomes the default.
Create a bucket with set_as_default: true to make it the default on creation.
Promote an existing bucket at any time with the Set Default Bucket endpoint. Promoting one bucket demotes the previous default.
The default bucket can’t be deleted. Set a different default first.

Routing: which bucket a file goes to

Every file context has an optional storage_config_id. That single field decides where a context’s uploads land — the mechanism is identical for both providers.

On upload

When a file is uploaded into a context, Uplint resolves the target bucket in this order:

The context’s storage_config_id, if it points to an active bucket.
Otherwise — unset, missing, or inactive — the tenant’s default bucket.

Binding a context to a bucket is just setting storage_config_id on the context. Send an empty string when updating a context to unbind it and fall back to the default bucket.

On download

Uplint records which bucket each file was written to, so files remain readable even after you add, rename, or re-route buckets. When serving a download it resolves the bucket in this order:

The file’s stored storage_config_id.
Otherwise, a bucket whose name matches the one recorded on the file (this keeps files uploaded before multi-bucket routing readable).
Otherwise, the tenant’s default bucket.

Because routing is resolved per file, re-pointing a context to a different bucket only affects new uploads. Existing files keep resolving to the bucket — and provider — they were originally written to.

Immutable fields

Once a bucket is created, its provider, its default_bucket (the S3 bucket or Azure container name), and its base_path cannot be changed — doing so would orphan every file already stored under them. To move data to a different bucket, container, or prefix, add a new storage bucket and route your contexts to it. You can always update the safe fields:

Field	Applies to	Why you’d change it
`name`	Both	Rename the bucket’s label.
`access_key_id` / `secret_access_key`	S3	Rotate AWS credentials.
`region`	S3	Reflect a bucket that has moved region.
`account_name` / `account_key`	Azure	Rotate Azure account credentials.
`is_active`	Both	Enable or disable the bucket for routing without deleting it.

Credential handling

Secrets — the AWS secret access key and the Azure account key — are encrypted at rest and are never returned by any endpoint.

S3: when you read a bucket, the access_key_id comes back masked (e.g. AKIA...MPLE) so you can recognize which key is in use without exposing it. To change it, submit a new access_key_id and secret_access_key.
Azure: the account_name is returned (it isn’t a secret), and the account_key is omitted entirely. To rotate it, submit a new account_key.

Use Update Storage Bucket to rotate credentials for either provider.

Deleting a bucket

Deletion is refused when the bucket is either:

the tenant’s default bucket, or
still bound to one or more file contexts.

Reassign or unbind those contexts (and, if needed, promote another bucket to default) before deleting. This guard prevents accidentally cutting off the storage that live contexts depend on.

Worked example

Amazon S3
Azure Blob
Google Cloud Storage

Add the S3 bucket

curl -X POST https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Claims",
    "provider": "aws_s3",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "ap-south-1",
    "default_bucket": "acme-insurance-claims",
    "base_path": "file-service/"
  }'

The response returns a config_id (e.g. cfg_a1b2c3d4e5f6). The access key comes back masked and the secret is omitted.

Route a context to it

curl -X PATCH https://api.uplint.dev/api/v1/contexts/insurance_claims \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "storage_config_id": "cfg_a1b2c3d4e5f6" }'

New uploads into insurance_claims now land in the acme-insurance-claims S3 bucket.

(Optional) Make it the default

curl -X POST \
  https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs/cfg_a1b2c3d4e5f6/set-default \
  -H "Authorization: Bearer ul_live_..."

Add the Azure container

curl -X POST https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Claims",
    "provider": "azure_blob",
    "account_name": "acmestorage01",
    "account_key": "base64AccountKeyFromThePortal==",
    "default_bucket": "acme-insurance-claims",
    "base_path": "file-service/"
  }'

default_bucket is the Azure container name. The response returns a config_id (e.g. cfg_a1b2c3d4e5f6); the account key is never returned. For sovereign clouds, add "endpoint_suffix": "core.usgovcloudapi.net" (or core.chinacloudapi.cn).

Route a context to it

curl -X PATCH https://api.uplint.dev/api/v1/contexts/insurance_claims \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "storage_config_id": "cfg_a1b2c3d4e5f6" }'

New uploads into insurance_claims now land in the acme-insurance-claims Azure container.

(Optional) Make it the default

curl -X POST \
  https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs/cfg_a1b2c3d4e5f6/set-default \
  -H "Authorization: Bearer ul_live_..."

Need a step-by-step for creating the Azure account, storage account, and container, and finding the account name/key? See the Azure Blob Storage setup guide.

Add the GCS bucket

curl -X POST https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Claims",
    "provider": "gcs",
    "access_key_id": "GOOG1EXAMPLEACCESSKEY",
    "secret_access_key": "gcs-hmac-secret-value",
    "default_bucket": "acme-insurance-claims",
    "base_path": "file-service/"
  }'

access_key_id / secret_access_key are your GCS HMAC key (Cloud Storage → Settings → Interoperability). The secret is never returned; no region is needed.

Route a context to it

curl -X PATCH https://api.uplint.dev/api/v1/contexts/insurance_claims \
  -H "Authorization: Bearer ul_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "storage_config_id": "cfg_a1b2c3d4e5f6" }'

New uploads into insurance_claims now land in the acme-insurance-claims GCS bucket.

(Optional) Make it the default

curl -X POST \
  https://api.uplint.dev/api/v1/tenants/tnt_9f8e7d6c/storage-configs/cfg_a1b2c3d4e5f6/set-default \
  -H "Authorization: Bearer ul_live_..."

Backward compatibility

Multi-bucket routing and multi-provider support are fully backward compatible. Tenants that already had a single S3 configuration keep working with zero changes: a config with no provider is treated as aws_s3, its existing config becomes the default bucket, and files uploaded before routing existed continue to resolve by their recorded bucket name. You only opt into more buckets — or into Azure or GCS — when you add one.

API reference

List storage buckets

Every bucket configured for the tenant.

Add a storage bucket

Get a storage bucket

Fetch a single bucket by ID.

Update a storage bucket

Rotate credentials, rename, or toggle active.

Set default bucket

Choose the tenant’s fallback bucket.

Delete a storage bucket

Remove an unused bucket.

Getting Started

Core Concepts

Team & Access

Storage Buckets

Overview

Choosing a provider

Why multiple buckets?

Data separation

Data residency

Independent credentials

Cost & lifecycle

The default bucket

Routing: which bucket a file goes to

On upload

On download

Immutable fields

Credential handling

Deleting a bucket

Worked example

Backward compatibility

API reference

List storage buckets

Add a storage bucket

Get a storage bucket

Update a storage bucket

Set default bucket

Delete a storage bucket

​Overview

​Choosing a provider

​Why multiple buckets?

Data separation

Data residency

Independent credentials

Cost & lifecycle

​The default bucket

​Routing: which bucket a file goes to

​On upload

​On download

​Immutable fields

​Credential handling

​Deleting a bucket

​Worked example

​Backward compatibility

​API reference

List storage buckets

Add a storage bucket

Get a storage bucket

Update a storage bucket

Set default bucket

Delete a storage bucket

Overview

Choosing a provider

Why multiple buckets?

The default bucket

Routing: which bucket a file goes to

On upload

On download

Immutable fields

Credential handling

Deleting a bucket

Worked example

Backward compatibility

API reference