PassPort app launch & app-entry

When a user opens your registered application, PassPort decides where it should land based on that user’s account state — a not-yet-set-up account can be routed to an onboarding screen, an active account straight into the app. This page covers declaring your app’s launch surface at registration and resolving the entry point at runtime.

All paths are under the public gateway at https://api.flexgalaxy.ai.

Declare your launch surface when you register

Register (or update) a service with POST /developer/v1/services. The service manifest’s surfaces.app_launch describes how your app is opened. Paths are relative — the platform resolves them against your app origin.

{
  "surfaces": {
    "app_launch": {
      "allowed_redirect_paths": ["/", "/auth/callback"],
      "launch_path": "/",
      "required_action": "open",
      "resource_frn_pattern": "frn:…:app/${account_id}",
      "onboarding_entry_url": "/welcome"
    }
  }
}

  • allowed_redirect_paths — the permitted post-sign-in return paths. Your app’s homepage is derived from the first entry that is not a /passport/… callback.

  • launch_path / required_action / resource_frn_pattern — the launch target and the authorization action + resource pattern checked when the app opens.

  • onboarding_entry_url (optional) — a distinct entry for accounts that are not yet active (see below). Omit it and every account opens at the homepage.

A newly registered service is reviewed and approved before it becomes launchable; until then app-entry resolution will not find an active application for it.

Resolve the entry point at runtime

On Open, call:

POST /passport/v1/app-entry/resolve

{ "appId": "<application id>", "accountId": "<account uuid>" }

Both fields are required. Note that the PassPort surface is camelCase, unlike the snake_case organization and account APIs.

accountId is not taken on trust: PassPort verifies that the account holds an active installation of the application, that your token was issued in that account’s organization realm, and that you are an assigned workforce member of that account, before it resolves anything.

The response tells you where to send the authenticated principal, keyed off that account’s lifecycle state:

{
  "appId": "<application id>",
  "accountId": "<account uuid>",
  "entryKind": "ONBOARDING",
  "deepLink": "/welcome?account_id=<account uuid>",
  "lifecycleStatus": "PLACEHOLDER",
  "displayName": "…"
}

Account lifecycle status

entryKind

Where deepLink points

PLACEHOLDER / MATERIALIZING

ONBOARDING

the app’s onboarding_entry_url, or the homepage if none was declared

ACTIVE

APP

the app homepage / launch path

no lifecycle record (an ordinary, non-onboarded account)

APP

the app homepage / launch path

CLOSED

—

409 account_closed; a closed account has no entry

deepLink always carries the resolved account as an account_id query parameter, appended with & when the configured URL already has a query string. lifecycleStatus is omitted for an account with no lifecycle record.

This is a signed-in (workforce / session) call — drive it from your app’s authenticated front end. An AK/SK service credential is rejected with 401.

Look up an application’s public metadata with:

GET /passport/v1/applications/{appId}

See also