Register an Application

Register your application once to get a client ID. The registration fixes the redirect URIs that Spiral sends users back to, and the most access your application can ever ask for. Users approve some or all of that access when they sign in. The Application uses the API of the stack that owns its Project.

PrerequisitesCopy Anchor Link

• Application management is turned on for your deployment.
• You have the Project admin role in the Project that owns the Application. A Project viewer can see its Applications but cannot change them.
• You use a first-party token, for example from spiral login. An Application token cannot manage Applications.

Register in StudioCopy Anchor Link

Studio is the quickest way to register an Application.

1. In Spiral Studio, open the Project, such as demo, and select Applications in the Project sidebar. The page shows the Applications of that Project.
2. Select Register application. Enter a name and the redirect URIs.
3. Under Who can sign in, select Your organization, or select Any organization, after Spiral review to offer the Application to other Organizations. See Who can sign in.
4. Select the Scopes field. Type to filter the scopes by name or description, then select the scopes that the Application needs. In the editor, expand the selected scope count to read their descriptions and open the permissions reference for the permissions each scope covers.
5. To return users to your application after installation, enter a Setup URL. Enable Redirect on update to also return after permission or Project changes. See Return users after installation.
6. To combine installation and user consent, enable Install during sign-in. It is off by default. An Organization owner can install on the consent page; other members can continue after the Application is installed. See Install during sign-in.
7. Select Save application.

Open Edit to copy the client ID into your application's configuration, or to change the registration. Use Suspend, Resume, or Delete to manage it. If you do not have access, Studio shows a permission message. Ask a Project admin for access, then select Try again.

Select Install to install the Application in your current Organization. If it is already installed, select Configure to review its current access with scope descriptions and use Edit access to request changes. The table shows only the number of registered scopes.

The rest of this guide does the same over HTTP.

Choose the scopesCopy Anchor Link

List the scopes that an Application can request:

curl https://api.spiraldb.dev/api/apps/scopes \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

Register only the scopes that your application needs, because users see each one on the consent page. To read or write Tables through ScanDAL, register tables:read or tables:write. See What an Application can access.

The registration accepts resource scopes, such as projects:read and tables:read. Request openid, profile, and email during sign-in when you need identity claims; these identity scopes are not entries in the registration's scope list. Including them in a registration returns InvalidArgument.

Create an Application over HTTPCopy Anchor Link

Create the Application in its Project. Send a name, the exact redirect URIs, and the scopes:

curl -X POST https://api.spiraldb.dev/api/apps/projects/demo \
  -H "Authorization: Bearer $SPIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frame Labeler",
    "redirectUris": ["https://labeler.example.com/oauth/callback"],
    "scopes": ["projects:read", "tables:read"],
    "enabled": true
  }'

The response is the Application. Its id is the client ID, such as client_01ABC, and its projectId is demo. Store the client ID in your application's configuration.

The Application stays in demo: it cannot move to another Project, and demo cannot be deleted while it has Applications.

These rules apply:

Creating is not idempotent: each create request generates a new client ID. If you lose a create response, list the Applications first, so you do not register the same application twice.

List and read ApplicationsCopy Anchor Link

curl -X POST https://api.spiraldb.dev/api/apps/projects/demo/list \
  -H "Authorization: Bearer $SPIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pageSize": 50}'

curl https://api.spiraldb.dev/api/apps/client_01ABC \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

The list includes the suspended and deleted Applications of the Project. If nextPageToken is present, send it as pageToken to read the next page.

Update or suspend an ApplicationCopy Anchor Link

Send the complete configuration. The update replaces the stored configuration. Set enabled to false to suspend sign-in and refresh:

curl -X PUT https://api.spiraldb.dev/api/apps/client_01ABC \
  -H "Authorization: Bearer $SPIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frame Labeler",
    "redirectUris": ["https://labeler.example.com/oauth/callback"],
    "scopes": ["projects:read", "tables:read"],
    "enabled": false
  }'

Set enabled to true to resume. A suspension does not end access tokens that were already issued. Preserve every configuration field that you still use, including the Setup URL and app authentication settings, because the update replaces the whole configuration.

Delete an ApplicationCopy Anchor Link

Deletion is permanent. The client ID cannot be used again, and every installation of the Application is removed.

curl -X DELETE https://api.spiraldb.dev/api/apps/client_01ABC \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

TroubleshootingCopy Anchor Link

Where next: sign users in to the Application.