Organizations
Put your team in one Spiral account, with shared sign-in and security settings.
An Organization is your company's account in Spiral. It holds your people, their roles, and the settings you configure once for everyone, such as single sign-on, directory sync, and audit logs. Your data does not live in the Organization directly. It lives in Projects inside the Organization, and each Project decides separately who can read and change it.
For example, a robotics company might have one Organization, acme. The
whole team signs in to acme with the company's single sign-on. Inside it, a
research Project is open to everyone, and a production Project is open
only to the data platform team and its ingest pipeline.
What an Organization holds
The Organization holds everything about who your team is. The Projects inside it hold everything about what your team works on.
| The Organization holds | Each Project holds |
|---|---|
| Members and pending invitations. | Tables and other Resources. |
| Single sign-on, directory sync, and verified domains. | Project roles and the grants that give them out. |
| Audit log, log stream, and encryption key settings. | The bucket that stores its data, and its usage. |
| The default storage for new Projects, and the buckets registered as Volumes. | The commit history of every change. |
Two Projects in one Organization can give access to the same people, but
they share nothing else: each has its own names, history, storage, and
grants. So a Table called frames can exist in both research and
production without one affecting the other.
Membership is not access
Joining an Organization lets a person sign in. It does not let them see any Project's data. Access comes from a separate Project grant, which gives a person, everyone with an Organization role, or a workload one role in one Project.
Because the two steps are separate, one person can be an admin in
research and have no access to production, while staying one member of
one Organization.
Organization roles
Each member has one Organization role:
| Role | Can do |
|---|---|
guest | List the Organization's Projects. |
member | Everything a guest can do, and create Projects. |
owner | Everything a member can do. Also invite and manage members, configure account settings, and register Applications. |
An Organization always keeps at least one owner, so Spiral rejects a role change or a deactivation that would remove the last one.
Organization roles do not decide what a person can do inside a Project.
Deleting a Project, for example, needs the Project admin role. New Projects
grant admin to Organization owners by default, but a Project admin can
revoke that grant. See
Access to a new Project.
Your active Organization
You sign in to one Organization at a time. Your access token names that Organization, and every Organization request applies to it. To work in another Organization, switch the active one; you do not need to sign in again. See Choose an Organization.
Where it runs
Spiral hosts the Organization API at https://api.spiraldb.dev/api/organizations
and the administration portal for account settings. Both are part of the
control plane, so they store membership and settings and never touch your
Table data. See Architecture.
HTTP API versions
Use /api/organizations for new HTTP integrations. Requests and responses use
camelCase field names and the shared error format.
List operations return nextPageToken; pass it unchanged with the same page size
and credential until it is absent. Lists reflect current state on each page.
Existing SDKs and the CLI continue to use /v1/organizations, which remains
available with its existing field names and responses.
Guides
- Manage members: invite people, change their roles, and deactivate them.
- Configure account settings: set up single sign-on, directory sync, domains, audit logs, log streams, and encryption keys.
- Organization CLI reference