Applications
Let the users of your application sign in with Spiral and approve what it can do for them.
When you build an application on Spiral, its users need to sign in, and the application needs to read and write data as them. Applications is the service that does this. You register your application once, and its users sign in with their Spiral account, see what your application asks to do, and approve it. Your application then gets a token that acts as that user, so you do not build your own login, store passwords, or invent your own permission checks.
For example, say you build Frame Labeler, a web app where your team tags the
camera frames in the frames Table of the demo Project. You register it in
demo with the scopes projects:read, tables:read, and tables:write, and an
Organization owner installs it for demo. When an engineer opens Frame Labeler,
it sends them to Spiral. They sign in, see
that Frame Labeler asks to read and write their Tables, and approve. Frame
Labeler gets a token that can read and write the Tables that engineer can
already read and write, and nothing more.
How it works
Signing in to an Application uses the standard OAuth 2.0 authorization code flow with PKCE, so any OAuth client library that supports PKCE works:
- Your application redirects the user to
https://auth.spiraldb.comwith its client ID and the scopes it wants. - The user signs in, selects an Organization, and approves the scopes on a consent page that names your application and the Organization that built it.
- Spiral redirects back to your application with a code, and your application exchanges the code for an access token and a refresh token.
- Your application calls Spiral with the access token, and refreshes it when it expires.
An Application is a public client: it has no client secret, so it is safe to ship in a browser app or a desktop app. Spiral records the user's approval, called consent, once for each Application, user, and Organization, and the user can withdraw it at any time. Because Spiral remembers the consent, a user who returns to a web Application that asks for no new scopes goes straight back to it. See Sign users in for the exact requests.
Who owns an Application
An Application belongs to one Project, such as
demo. Viewers of the Project can see its Applications, and only a Project
admin can create, change, suspend, or delete them. Management is limited to
administrators because the redirect URIs decide where Spiral sends your users'
sign-ins: whoever can change them can receive those sign-ins.
An Application stays in the Project where you create it; it cannot move to another Project. A Project that has Applications cannot be deleted, so delete its Applications first.
What an Application can access
A registered Application's user token can access Projects and resources only when all of these allow it:
- the user's current permissions, from their Project grants, and
- the scopes the user approved, and
- the scopes and Projects in the Organization's active installation.
Without an approved installation, sign-in and setup discovery remain available, but Project access is denied. An installation cannot give a user permissions that the user does not already have.
Because the user's permissions are checked on every request, an Application
loses access as soon as the user does. If an admin revokes the engineer's
editor role in demo, Frame Labeler can no longer write frames for them,
even though the user approved tables:write.
A registration lists the most scopes your application can ask for, and each sign-in requests some or all of them:
| Scope | The user allows the Application to |
|---|---|
projects:read | See your projects. |
catalog:read | See catalog branches, commits, and history. |
catalog:write | Publish commits and create, merge, and delete branches. |
tables:read | Read tables and vector indexes. |
tables:write | Create and write tables and vector indexes. |
locations:read | Read files in locations. |
locations:write | Create, change, and remove locations. |
compute:read | See tasks, compute, and worker pools. |
compute:run | Run and cancel tasks, which can incur cost. |
connections:read | See connections, without their credentials. |
GET /api/apps/scopes returns the same list with its descriptions. The
standard openid, profile, and email scopes let your application read the
user's identity from https://auth.spiraldb.com/userinfo.
Limits of Application tokens
An Application token acts for a user, but it cannot do everything the user could do when they sign in to Spiral directly:
- It cannot read the user's account profile or list their Organizations
through the Spiral API. Use
/userinfofor identity claims. - It cannot manage Applications.
- It cannot create, change, or resume Task Automations. With the right scopes and permissions, it can submit Tasks, and pause or delete Automations.
- It gets storage access that expires no later than the Application token itself, and signed storage URLs that expire within five minutes.
- It cannot get cloud credentials from a Connection, including through a Location.
Each refresh checks again who can sign in, the user's consent, and the Application's registered scopes. A refresh can ask for fewer scopes, and the new access token then has only those.
Who can sign in
Three settings decide whether a user can sign in to an Application. Each one belongs to a different party, so the developer, Spiral, and the user's own Organization all have a say:
| Setting | Who sets it | Effect |
|---|---|---|
| Audience | A Project admin of the Application | internal, the default, admits only users of the Organization that owns the Application. public also admits users of other Organizations. |
| Review | Spiral | A public Application acts as internal until Spiral reviews it. |
| App access | The owner of each Organization | Allows or blocks each Application, and decides what happens to Applications that the Organization did not list. |
For example, Frame Labeler starts as internal, so only your own team can
sign in. To offer it to other Organizations, set its audience to public and
ask Spiral to review it. After the review, users of another Organization can
sign in, unless that Organization's owner blocks Frame Labeler.
A user who cannot sign in sees the reason, such as "Contact us to use this app." when the Application is not available to their Organization, or "Your organization has blocked this app." when their owner blocked it. Spiral checks these settings again at every refresh, so a change also stops existing sessions.
Control which Applications your users can sign in to
By default, an Organization allows every Application that Spiral reviewed. An
Organization owner can block one Application, allow one that Spiral has not
reviewed, or block every Application that the owner did not allow. These
decisions also apply to MCP clients, such as AI assistants, that users connect
to Spiral.
Read the current setting with GET /api/apps/organization-access, and replace
it with PUT on the same path. This request allows one MCP client and blocks
every other unlisted client:
curl -X PUT https://api.spiraldb.dev/api/apps/organization-access \
-H "Authorization: Bearer $SPIRAL_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"unlisted": "block",
"clients": [
{ "clientId": "https://claude.ai/oauth/mcp-oauth-client-metadata", "decision": "allow" }
]
}'unlisted is allow_reviewed (the default) or block. The decision for a
listed client applies before unlisted. Use a token from your own sign-in to
Spiral; an Application token cannot change app access.
Suspending and deleting
A new Application is active. Set enabled to false to suspend sign-in and
refresh, and back to true to resume. Deleting an Application is permanent,
and its client ID cannot be used again. Both stop Spiral from issuing new
tokens, but access tokens already issued keep working until they expire. See
Register an Application.
Deleting an Application also uninstalls it from every Organization. Users can also stop an Application themselves, from Connected applications in Studio.
Background work
Some Applications work without a signed-in user, for example to process new
frames as they arrive. An Organization can install such an Application: the
installation is the Application's own identity in that Organization, with the
scopes and Projects that an Organization owner approves. It keeps working
when the person who installed it leaves. See
Install an Application.
Availability
Application management is in development, and it works only on deployments where Spiral has turned it on. Installations for background work are also in development.
Where it runs
Spiral hosts the Applications API, which stores the registrations of your
Projects, the app access of your Organization, and its installations, at https://api.spiraldb.dev/api/apps. The authorization
server at https://auth.spiraldb.com signs users in, shows the consent page,
and issues tokens to your application. See
Architecture.
Guides
- Register an Application to get a client ID.
- Sign users in from your application.
- Install an Application for background work.
- Return users after installation with a Setup URL and verified approval state.
- Manage connected applications as a user.