Return users after installation

Send users from your application to Studio to choose an Organization's Projects and request or approve access. A registered Setup URL brings them back to your application after they save, so they can continue where they left off. For example, Frame Labeler can open the frames Table once the Organization approves access to demo.

PrerequisitesCopy Anchor Link

• Register the Application, including every resource scope it requests.
• Sign the user in for the Organization that will use it. Include projects:read to discover the installation and its accessible Projects.
• Use Studio and the API serving that Organization. The examples use https://studio.spiraldb.com and https://api.spiraldb.dev. For another region or a local deployment, use that deployment's Studio URL and API URL.

Signing in and approving an installation are separate steps. A registered Application can sign a user in before installation, but its Project access requires an active installation as well as the user's permissions and consented scopes. See Application access.

Configure the return addressCopy Anchor Link

In the developer Project's Applications page, open Edit for the Application:

1. Set Redirect URIs to the OAuth callbacks used by your sign-in library.
2. Set Setup URL to a page such as https://labeler.example.com/setup/complete.
3. Enable Redirect on update if you also want users to return after changing an existing installation's permissions or Projects.
4. Save the Application.

The two addresses have different jobs:

The Setup URL is optional. Without it, users remain in Studio after setup. Redirect on update defaults to off and requires a Setup URL. The registration API names these fields setupUrl and redirectOnUpdate.

Use HTTPS, or HTTP on localhost, 127.0.0.1, or [::1] for local development. The URL can contain your own query parameters, but installation_id, setup_action, and state are reserved. Credentials and fragments are not accepted. The URL is limited to 2048 bytes.

Open the installation pageCopy Anchor Link

Create a random, single-use state value and store it in your application's session with the expected Organization and client ID. Use a short opaque value, such as a base64url nonce; Studio accepts up to 512 characters. Keep application data and credentials in the session, because the state appears in browser URLs.

Send the browser to this address, replacing the Organization ID, client ID, and state and URL-encoding each value:

https://studio.spiraldb.com/organizations/org_customer/applications?install=client_example123&state=RANDOM_SINGLE_USE_NONCE

The Organization in the path is the customer Organization that receives the installation, which can differ from the developer Organization. The install parameter is the Application's client ID. Studio opens its review dialog directly. If the user needs to sign in to Studio first, Studio preserves the installation link and state through sign-in.

The user reviews the publisher, scopes, and Projects before submitting. An Organization owner can approve immediately. Another member sends a request for an owner to review. See Install and review in Studio.

A signed-in user's token reads this link, without state, as configurationUrl from GET /api/apps/user/installation, whether or not an installation exists. Append your state to it instead of building the link.

The link never chooses the return destination: Studio reads the Setup URL from the Application's registration. Passing redirect_uri or returnTo on this installation link does not override it.

Handle the returnCopy Anchor Link

After a successful save, Studio opens the registered Setup URL:

https://labeler.example.com/setup/complete?installation_id=inst_example123&setup_action=install&state=RANDOM_SINGLE_USE_NONCE

The browser version returns in the current tab. Desktop Studio opens the Setup URL in the system browser.

Treat these parameters as navigation information. Anyone can construct the same URL, and the installation may change after the redirect. At your Setup URL:

1. Match state to the pending request in the current application session, check its expiry, and consume it once.
2. Read the installation with your application's authenticated API client. Check its Application, Organization, current status, and approved scopes.
3. Check the Projects available through that credential before continuing. Show a pending-approval page when the requested access is not approved.

The URL contains no OAuth code or token. It does not sign the user into your application or grant access by itself.

For a signed-in user, use their Application token, including projects:read, as $SPIRAL_TOKEN:

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

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

The first response contains installation, or null if none exists, and the installation link as configurationUrl. Compare the installation's id with the returned installation_id, and its applicationId and organizationId with your session. Check status, approvedScopes and approvedAllProjects; a saved request does not grant its requestedScopes. The second call lists only Projects allowed by the user's permissions and the active installation. Both the user token and the installation need projects:read for that list. Follow nextPageToken when present.

If your backend authenticates as the Application itself, it can instead read GET /api/apps/self/installations/{installation_id}. This checks that the installation belongs to that Application and returns its requested and approved grants. A user token cannot call that endpoint. See Act as an installation for background work.

An owner can approve a request directly in Studio later. That returns the owner's browser to the Setup URL without the original requester's state. The original requester is not redirected a second time. Without a matching pending state, show an informational page or start sign-in; do not associate the returned installation with an arbitrary application session.

Ask for more accessCopy Anchor Link

Add any new resource scopes to the Application's registration first. Then open the same installation link with a fresh state. Studio shows the current installation, and the user requests or approves the new scopes and Projects. The previously approved grant remains in effect until an owner approves the change.

With Redirect on update enabled, Studio returns after saving a change or request for an installation that already has an approved grant. With it disabled, those updates stay in Studio. First-time installation requests and approvals return whenever a Setup URL is configured.

If user actions also need new OAuth scopes, start a new authorization request with the larger scope set. The user's consent and the Organization's approval are both required. Updating the installation does not expand an existing user token, and refreshing cannot add scopes beyond its original consent.

TroubleshootingCopy Anchor Link

Where next: sign users in and manage installation access.