1---
2name: spaces
3description: create and manage spaces, configure access control, set up custom domains, and understand the identity model
4---
5
6# spaces
7
8a 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.
9
10## creating a space
11
12```
13POST https://api.sublimated.com/v1/spaces
14{ "slug": "my-project" }
15```
16
17or via git — pushing to a new slug auto-creates the space.
18
19## space types
20
21- `personal` — default, owned by a user
22- `org` — organization space (shared ownership)
23
24## visibility
25
26- `private` — only authenticated users with access rules can read
27- `public` — anyone can clone/read, writes still require auth
28
29set via API or `.sublimated/access.yml`.
30
31## access control
32
33access is configured per-space via `.sublimated/access.yml`, pushed through git:
34
35```yaml
36rules:
37  - identifier: alice
38    role: editor
39  - identifier: "*@company.com"
40    role: viewer
41  - identifier: "*"
42    role: viewer
43    paths: ["docs"]
44```
45
46roles (highest to lowest privilege): owner, admin, editor, commenter, viewer.
47
48rules support:
49- username: `alice`
50- email: `bob@example.com`
51- domain wildcard: `*@company.com`
52- public wildcard: `*` (anonymous access)
53- path scoping: restrict access to specific folders
54
55access config is parsed, merged hierarchically (deeper folders override parents), and cached in KV for fast lookups.
56
57## scoped tokens
58
59create tokens with restricted permissions:
60
61```
62POST https://api.sublimated.com/v1/spaces/{slug}/tokens
63{
64  "label": "CI deploy",
65  "permissions": ["read", "write"],
66  "pathScope": ["src"],
67  "branchPatterns": ["refs/heads/main"],
68  "expiresIn": "30d"
69}
70```
71
72token prefix: `sk_`. use as Bearer token or git password.
73
74## identity model (progressive trust)
75
76- level 0: anonymous — auto-created on first interaction, gets personal space + scoped token
77- level 1: email verified
78- level 2: identity linked (GitHub, etc.)
79- level 3: full account
80- level 4: system only (internal service account)
81
82anonymous users can push to their own space immediately — no signup friction.
83
84## item hierarchy
85
86items are organized as ltree paths: `slug.folder.subfolder.file-md`
87
88- every folder is independently clonable as a git repo
89- items track: name, type, path, contentHash, sizeBytes, currentVersion
90- folders are implicit from paths but also stored as items (for metadata, permissions)
91
92## quotas
93
94spaces can have limits:
95- `maxStorageBytes` — storage cap
96- `maxRequestsPerDay` — API rate limit
97
98when usage exceeds 80%, a persistent warning appears on every response. at 95%+, severity escalates to error.
99
100## space configuration
101
102`.sublimated/config.yml` in the space root configures:
103- build settings (which branches trigger Docker builds)
104- custom domain mappings
105- default visibility
106- feature flags
107
108pushed via git, parsed on push, takes effect immediately.
109
110## see also
111
112- git-workflow — clone and push to spaces
113- data-api — API endpoints for space management
114- connectors — sync external data into a space