Create and configure a workspace

See Definition for what a Workspace actually is relative to a bucket, and Authorization for the full role model this guide only walks through the common calls of. Every request below is superuser-only (registering, deleting, and reconfiguring a workspace are instance-wide actions, not scoped to one workspace’s own roles).

1. Register the bucket

Either adopt a bucket that already exists, or have Atlas create one:

# Create a brand-new bucket and register it in one call
curl -b cookies.txt -X POST http://localhost:8000/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{"bucket": "invoices", "create_new": true, "versioning": true, "object_lock": false}'

# Or register a bucket that already exists in the account
curl -b cookies.txt -X POST http://localhost:8000/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{"bucket": "invoices", "create_new": false}'

versioning/object_lock only apply when create_new: true — adopting an existing bucket leaves its current settings untouched. The same form is available from the admin UI’s Workspaces page.

Note

object_lock: true can only be set at bucket creation — S3 doesn’t allow enabling Object Lock on a bucket after the fact. If you need it on an already-existing bucket, it has to be recreated.

2. Grant roles

A role isn’t granted to one person at a time — it’s granted to a rule, matched against every principal on each request:

curl -b cookies.txt -X POST http://localhost:8000/api/v1/workspaces/{workspace_id}/roles \
  -H "Content-Type: application/json" \
  -d '{"role": "MEMBER", "grant_match": {"groups": "finance"}}'

Goal	grant_match
One specific person	{"id": "alice"}
An entire OIDC group	{"groups": "finance"}
Every API key (service accounts)	{"type": "API"}

Matching on groups only works if your OIDC scope actually returns it — see Configure SSO with Keycloak. Pick READER, MEMBER, or MANAGER depending on how much access the rule should carry; the full grid is in Authorization.

3. Turn on auto-index (optional)

By default, a tusd upload into this bucket lands in S3 but isn’t declared as a Document until someone (or some script) does so explicitly. To have every finished upload auto-declared instead:

curl -b cookies.txt -X PATCH http://localhost:8000/api/v1/workspaces/{workspace_id} \
  -H "Content-Type: application/json" \
  -d '{"auto_index_on_upload": true}'

Same toggle, same admin table, in the UI’s Workspaces page.

4. Adjust bucket-level settings (optional)

These are native S3 settings, not Atlas-specific — set directly on the bucket, independent of any workspace role:

# Lifecycle: expire objects under a prefix after N days
curl -b cookies.txt -X PUT http://localhost:8000/api/v1/buckets/invoices/lifecycle \
  -H "Content-Type: application/json" \
  -d '{"rules": [{"id": "expire-scratch", "prefix": "scratch/", "expiration_days": 30, "enabled": true}]}'

# Default encryption
curl -b cookies.txt -X PUT http://localhost:8000/api/v1/buckets/invoices/encryption \
  -H "Content-Type: application/json" \
  -d '{"encryption": {"algorithm": "AES256"}}'

# Versioning (already on if you registered with versioning: true above)
curl -b cookies.txt -X PUT http://localhost:8000/api/v1/buckets/invoices/versioning \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

At this point the workspace is registered, has at least one role granted on it, and its bucket is configured the way you want — ready for documents to be declared, searched, and linked.