Buckets and Keys

A files service is one S3-compatible bucket. This page covers creating the service, reading the bucket coordinates, minting scoped access keys, and revoking them.

Create a Files Service

curl -u admin:password -X POST \
  https://api.foundrydb.com/file-services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-uploads",
    "zone": "se-sto1"
  }'

The response returns the service in Pending status. Poll until it reaches Running:

curl -u admin:password \
  https://api.foundrydb.com/file-services/{id}

The files_config field in the response carries the bucket coordinates once provisioning completes:

{
  "id": "f0e1d2c3-...",
  "name": "my-uploads",
  "status": "Running",
  "files_config": {
    "buckets": [
      {
        "region": "europe-1",
        "bucket": "files-f0e1d2c3",
        "endpoint": "https://eu.files.foundrydb.com"
      }
    ],
    "quota_gb_soft": 400,
    "quota_gb_hard": 500,
    "versioning": true,
    "sse": true,
    "lifecycle_enabled": true,
    "measured_bytes": 0,
    "over_quota": false
  }
}

Request Fields

Field	Required	Description
name	Yes	Service name, 3–63 characters, unique to the owner
zone	No	Provider zone. Defaults to the platform default. Only zones in the europe and us peering regions are supported
quota_gb_soft	No	Soft quota in GB (default: 400)
quota_gb_hard	No	Hard quota in GB (default: 500)
organization_id	No	Assign the service to an organization; the caller must be a member

S3 Coordinates

Once the service is Running, retrieve your bucket coordinates from files_config.buckets[0]:

Value	Where to find it	Example
Endpoint	files_config.buckets[0].endpoint	https://eu.files.foundrydb.com
Bucket name	files_config.buckets[0].bucket	files-f0e1d2c3
Region	files_config.buckets[0].region	europe-1

Mint an Access Key

Access keys are scoped credentials. Each key is tied to a permission level and an optional object key prefix. The secret half is shown exactly once in the creation response; there is no reveal endpoint. Store it immediately.

curl -u admin:password -X POST \
  https://api.foundrydb.com/file-services/{id}/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-uploads",
    "permissions": "readwrite",
    "prefix": "uploads/"
  }'

Response:

{
  "id": "a1b2c3d4-...",
  "name": "backend-uploads",
  "access_key_id": "EXAMPLEkeyid",
  "secret_access_key": "EXAMPLEsecret",
  "prefix": "uploads/",
  "permissions": "readwrite",
  "status": "active"
}

The secret_access_key field is present only in this response.

Key Request Fields

Field	Required	Description
name	Yes	Label for the key, up to 128 characters
permissions	Yes	read, write, or readwrite
prefix	No	Object key prefix to scope the key to, for example uploads/. Must not start with /, contain .., or contain whitespace. Empty grants access to the whole bucket

Permission Levels

Value	Grants
read	GetObject, ListBucket (constrained to prefix when set)
write	PutObject, DeleteObject, GetObject
readwrite	All of the above

These permissions are compiled into the object storage provider's own IAM policy and enforced by the provider, not by the platform layer.

List Access Keys

curl -u admin:password \
  https://api.foundrydb.com/file-services/{id}/keys

The response includes all customer-managed keys for the service. Secret halves are never included. The platform's internal service key is excluded from this listing.

Revoke an Access Key

Use the key's id (the UUID field), not the access_key_id string:

curl -u admin:password -X DELETE \
  https://api.foundrydb.com/file-services/{id}/keys/{key-id}

Revocation deletes the provider-side IAM user, policy, and access key, then destroys the stored secret. The operation is idempotent: retrying a revocation converges even if some resources were already removed. A 204 No Content response confirms completion.

Revocation is permanent. Mint a new key to restore access.

Delete a Files Service

curl -u admin:password -X DELETE \
  https://api.foundrydb.com/file-services/{id}

Deletion removes the bucket contents, the bucket itself, and every credential minted for the service. This is irreversible.

What's Next

• Using S3 Clients — upload and download with the AWS CLI and SDKs
• Attach to Apps — automatic credential injection for hosted apps