An installation is the link between a user account and your app. Orceum tracks its state, securely stores the user’s credentials, and uses those credentials to route action calls on the user’s behalf. As an app developer, you don’t need to build any installation logic. Orceum handles the entire UI and credential management process when a user clicks Install in the Orceum Store.

​
What Happens During Installation

The user’s experience depends entirely on the Authentication Method you configured for your app in the Developer Studio.

​
None (No Authentication)

The app installs instantly. The installation becomes ACTIVE immediately, and your app is ready to receive action calls.

​
API Key Flow

  1. The user clicks Install.
  2. Orceum prompts the user to enter their API key (displaying any instructions or format hints you configured in the Developer Studio).
  3. The user submits the key. Orceum validates that it meets minimum requirements (e.g., at least 8 characters).
  4. Orceum encrypts the key at rest.
  5. The installation becomes ACTIVE.
  6. On every action call, Orceum decrypts the key and injects it into the HTTP header you specified.

​
OAuth Flow

  1. The user clicks Install.
  2. Orceum dynamically builds the authorization URL using your configured client_id and scopes.
  3. The user is redirected to your OAuth provider’s consent screen.
  4. After granting access, the provider redirects the user back to Orceum’s callback URL.
  5. Orceum exchanges the authorization code for an access token (and refresh token).
  6. The tokens are encrypted at rest, and the installation becomes ACTIVE.
  7. Orceum handles all token refreshes automatically in the background.

​
Installation States

An installation transitions through these states automatically:
StateDescription
PENDINGJust created — awaiting credential submission (e.g., user is on the OAuth consent screen).
ACTIVECredentials validated — app can execute actions.
SUSPENDEDTemporarily disabled (due to admin action or repeated execution errors).
UNINSTALLEDUser removed the app — credentials cleared, tokens revoked.
REAUTH_REQUIREDOAuth tokens expired or became invalid — the user must re-authenticate.

​
State Transitions

PENDING
  ├─→ ACTIVE          (credentials submitted and validated)
  └─→ UNINSTALLED     (user cancels installation)

ACTIVE
  ├─→ SUSPENDED       (admin suspends or repeated failures)
  ├─→ UNINSTALLED     (user removes the app)
  └─→ REAUTH_REQUIRED (token refresh fails)

REAUTH_REQUIRED
  └─→ ACTIVE          (user re-authenticates)

SUSPENDED
  └─→ ACTIVE          (admin re-enables)

​
Re-authentication

If your app uses OAuth and the refresh token expires or is revoked on your end, the next action call will fail with a 401 Unauthorized. When this happens, Orceum automatically transitions the installation to REAUTH_REQUIRED. The AI assistant will pause execution and prompt the user with a secure link to re-authenticate. Once they complete the OAuth flow again, the installation becomes ACTIVE and the AI resumes its task.

​
Lifecycle Webhooks

When a user successfully installs or uninstalls your app, Orceum can notify your backend. You configure your Installation Webhook URL in the Developer Studio. See Lifecycle Webhooks for the full payload schema and verification guide.