Authorization
Decide what each person, workload, and application can do in a Project.
Each Project decides who can read and change its data. You give access by
granting a role (viewer, editor, or admin) to a person, to everyone
with an Organization role, or to a workload.
Nothing else gives access. Being a member of the Organization lets a person
sign in, but they cannot see a Project's Tables until someone grants them a
role in that Project.
A typical setup for the demo Project gives the whole team viewer, gives
the nightly-curation workload editor so it can write to the frames
Table, and gives two team leads admin. Your application's users get the
same kind of grants, so the access rules you set here are the rules your
application follows.
Roles
There are three Project roles. Each one includes everything the role before it can do:
| Project role | Can do |
|---|---|
viewer | View the Project. Read the Catalog, Tables, Vector Indexes, and Locations. View workloads, Applications, Connections, Tasks, and Worker Pools. |
editor | Everything a viewer can do. Also create and write Tables, Vector Indexes, and Locations, publish to the Catalog, manage branches and tags, create workloads, create Connections, submit and cancel Tasks, and manage Worker Pools. |
admin | Everything an editor can do. Also view and grant Project roles, manage the keys and trust policies of workloads, manage Applications, change Project storage, delete the Project, and obtain a Connection credential directly. |
Give each principal the narrowest role that covers its work: a dashboard
needs viewer, and an ingest pipeline needs editor. The
permissions reference lists every permission
in each role.
Organizations have their own roles, owner, member, and guest, which
control the account rather than its data. See
Organization roles.
Who you can grant a role to
A grant gives one principal one role in one Project. A principal is anything that can sign in and make a request:
| Principal | Matches | Example |
|---|---|---|
| Organization user | One person in one Organization. | Give one analyst editor. |
| Organization role | Everyone with that Organization role, now and in the future. | Give every member viewer. |
| Workload | One workload. | Give nightly-curation editor. |
A principal can hold several grants, and it can do anything that any of its roles allows. Grants to an Organization role are how you open a Project to a whole team without listing each person.
Access to a new Project
When someone creates a Project, Spiral gives the creator the admin role and
adds one grant for each Organization role:
| Organization role | Project role |
|---|---|
owner | admin |
member | viewer |
guest | viewer |
These are ordinary grants, so a Project admin can revoke them. For example,
revoke the member and guest grants to restrict a Project to a small team.
See Grant Project access.
Applications act for a user
When a user signs in to an Application, the Application acts as that user, and its access is limited twice. It can do only what the user's grants allow right now, and only what the scopes the user approved allow. If either one does not include a permission, the request fails. So revoking a user's grant also takes that access away from every Application they use.
Connection credentials
A Connection holds one credential for an external system, such as Hugging Face. Its operations use the same three roles:
| Operation | viewer | editor | admin |
|---|---|---|---|
| See Connection names and types, and read one Connection's metadata | ✓ | ✓ | ✓ |
| Create or replace a Connection, update its credential, change its description, test it, drop it | ✓ | ✓ | |
| Name a Connection from a Location | ✓ | ✓ | |
| Obtain a credential directly, with no Location behind it | ✓ |
No role can read a stored secret. A read reports only whether a secret is present and when it was last set.
Reading a Location that names a Connection needs
only the Location's permissions, because Spiral checks the Connection when
someone creates the Location. Obtaining a credential directly is admin
only, because it gives the caller something usable outside Spiral that no
Location records.
Where it runs
Spiral hosts the grant API at https://api.spiraldb.dev. Every Spiral
service checks the caller's grants before it returns data or storage
credentials, so your application's code never decides permissions itself.
See Architecture and
Access.
HTTP API
New HTTP integrations use /api/authorization. Grants use a role and a typed
principal. List responses contain items and an optional nextPageToken;
follow it with the same credential, filters and page size until absent.
Installation review returns the edges transitioned by one atomic decision.
See the HTTP reference.
Guides
- Grant Project access to users, Organization roles, and workloads.
- Manage members of the Organization.
- Create a workload for a pipeline or service.