Substratal Apps — Platform API
When your business is building applications, Substratal Apps removes the user-management burden: one API for user accounts, settings, organizations/tenancy, and per-user storage, so a developer can focus entirely on the app they’re actually trying to build.
This site specifies that API: who a user is, what they’re allowed to touch within a given app, and how each app’s own settings and data are stored and scoped. It is API-first — no end-user interface is specified here. A dashboard that makes onboarding easier is planned, but it’s a client of this API, built later, not a requirement to use it today.
What Substratal Apps actually is
Think of it as the user/organization/tenancy layer that an app developer would otherwise have to build themselves — comparable in shape to Auth0, Clerk, or WorkOS, but scoped around the full set of things a multi-tenant app needs from day one, not just login: accounts, per-app and per-org settings, team/tenancy structure, and a place to store the app’s own per-user data, all behind one API.
An Application in this spec is one developer’s app, built on top of Substratal Apps for that layer. Substratal builds its own, and outside developers register theirs through self-service registration. The Entitlement that gates a user’s access to an app, and the billing relationship behind it, belongs to that app’s own developer:
- A third-party developer charges however they want, or not at all. Their app doesn’t have to use any particular payment processor, and it can be free. Substratal Apps is then its distribution, account, and settings layer. The developer either opens the app to every User or grants access themselves from their own billing (
access_tierfreeorrestricted). Substratal never takes a cut or processes their payments. - Substratal’s own apps are billed by Substratal to the people who use them, through the Free/Standard subscription on Pricing. That subscription covers Substratal’s own apps only, never a third-party one.
What this site is
This is a living specification and the system of record for the platform API. It isn’t a one-time design doc — as decisions get made and the API gets built, this site is where that gets reflected. If this site and a conversation, a Slack thread, or an old draft disagree, this site wins; update it the moment something here goes stale.
It’s written to be read by people building the API and by AI coding tools asked to work against it — see /llms.txt for a machine-oriented index of every page.
How it’s organized
| Section | Answers |
|---|---|
| Getting Started | Where to start if you’re new to this — human or AI tool. |
| Quickstart | A runnable curl walkthrough — create a user, grant an app, check access, turn it off. |
| Domain Model | What are the core entities, and how do they relate? |
| Access Control | Given a user and an app, what decides if a request is allowed? |
| API Reference | What are the actual resources, endpoints, and payloads? Includes Auth (signup, login, app tokens), Push Notifications (alerts and updates to a User’s devices, and their inbox), and Billing (the Free/Standard subscription). The OpenAPI Specification section renders the whole contract as interactive Swagger UI. |
| OpenAPI Specification | The full contract as OpenAPI 3.1: interactive Swagger UI, download, client generation, and how to read it. |
| Workflows | How do the pieces move together for real scenarios — a purchase, an admin revoking access, a role change? |
| Trust Model | How does a separately-hosted app verify a user’s access without maintaining its own user table? |
| MCP Server | How does an AI agent call this API directly, as a tool-using client rather than writing HTTP calls by hand? |
| Non-Functional Requirements | Security, multi-tenancy, audit, rate limits, versioning. |
| Compliance & Data Protection | Which of SOC 2, HIPAA, GDPR, and CCPA apply, and when to act on each. |
| Legal | Terms of Service, Privacy Policy, EULA, Developer Terms, the Data Processing Addendum, and the other agreements, at stable URLs. |
| Roadmap | What ships in the MVP vs. later phases. |
| Pricing | Free and Standard ($6.99 per user per month, or $76.99 per year) — what people using Substratal’s apps pay, individually or through an Organization. |
| Changelog | What’s changed in this spec over time. |
| Glossary | Precise definitions for every term used here. |
The one idea worth remembering
Two questions get asked, separately, every time a user touches an app:
- Is the app itself switched on for this user? This is the Entitlement — a literal on/off record, independent of what the user could do if it were on. An admin flipping a user’s access to an app off is a write to this record, nothing else.
- If it’s on, what can they do? This is the Role — platform-wide or scoped to that one app — resolved into a set of Permissions.
Everything else in this spec (profiles, settings, orders, audit) hangs off of that split. See Access Control for the full model.
This site is self-hosting its own context: it’s generated from Markdown committed to this same repository, under docs/, via GitHub Pages. It’s deliberately scoped to the API specification itself: how a developer or their AI agent builds against this API. How it’s deployed is in the repository’s infra/README.md, and what’s left to build is in plan-remaining.md; the repo’s README.md maps what’s where.