spaces

name: spaces
description: create and manage spaces, configure access control, set up custom domains, and understand the identity model

a space is the top-level container in sublimated. every space has a unique slug, an owner, and contains items (files and folders) organized as an ltree hierarchy.

creating a space

POST https://api.sublimated.com/v1/spaces
{ "slug": "my-project" }

or via git — pushing to a new slug auto-creates the space.

space types

• personal — default, owned by a user

• org — organization space (shared ownership)

visibility

• private — only authenticated users with access rules can read

• public — anyone can clone/read, writes still require auth

set via API or .sbl/access.yml.

access control

access is configured per-space via .sbl/access.yml, pushed through git:

rules:
  - identifier: alice
    role: editor
  - identifier: "*@company.com"
    role: viewer
  - identifier: "*"
    role: viewer
    paths: ["docs"]

roles (highest to lowest privilege): owner, admin, editor, commenter, viewer.

rules support:

• username: alice

• email: bob@example.com

• domain wildcard: *@company.com

• public wildcard: * (anonymous access)

• path scoping: restrict access to specific folders

access config is parsed, merged hierarchically (deeper folders override parents), and cached in KV for fast lookups.

scoped tokens

create tokens with restricted permissions:

POST https://api.sublimated.com/v1/spaces/{slug}/tokens
{
  "label": "CI deploy",
  "permissions": ["read", "write"],
  "pathScope": ["src"],
  "branchPatterns": ["refs/heads/main"],
  "expiresIn": "30d"
}

token prefix: sk_. use as Bearer token or git password.

identity model (progressive trust)

• level 0: anonymous — auto-created on first interaction, gets personal space + scoped token

• level 1: email verified

• level 2: identity linked (GitHub, etc.)

• level 3: full account

• level 4: system only (internal service account)

anonymous users can push to their own space immediately — no signup friction.

item hierarchy

items are organized as paths: slug/folder/subfolder/file.md

• every folder is independently clonable as a git repo

• items track: name, type, path, contentHash, sizeBytes, currentVersion

• folders are implicit from paths but also stored as items (for metadata, permissions)

space configuration

.sbl/config.yml in the space root configures:

• build settings (which branches trigger Docker builds)

• custom domain mappings

• default visibility

• feature flags

pushed via git, parsed on push, takes effect immediately.