Skip to main content

Hosted Action

Hosted Action is a Hosted UI mode for pages that open from a short link (?code=): prove who the user is, resolve the deeplink, then run the action (for example accept a KYC invitation). Hosted Auth is the separate mode for login portals (sign-in, sign-up, employee/member access groups).

You pick the mode once when you create the application in the Developer Portal (hostedUiType). It is immutable after create — use two applications if you need both a login portal and action landings.

Hosted Auth (HOSTED_AUTH)Hosted Action (HOSTED_ACTION)
Typical URL/login, /signup on your siteYour action page URL with ?code=
Portal fieldsUser type, member access, groupsAction page URL (HTTPS, non-localhost)
SDK entryInitiateAuthFlow inside HostedUiProviderHostedInvite or HostedActionShell
Sign-up link on phone stepShown when allowSignup is trueHidden — one phone screen
Initiate authActionsignin or signupauto (server picks sign-in vs sign-up)
Not the OAuth IDP app type

Hosted UI (Auth or Action) is not the Identity Provider (SSO) application. IDP is for “Login with ChainIT” redirects; Hosted Action is for branded deeplink landings on your page.

End-to-end flow​

Register the action page URL in the portal so resolver redirects land on the route where you mount the SDK.

Developer Portal setup​

When you create a Hosted UI application:

  1. Choose Hosted UI type → Hosted Action (not Hosted Auth).
  2. Set Action page URL — public HTTPS URL of the page that hosts HostedInvite (for example https://app.example.com/kyc/invite). Localhost is not valid for this field.
  3. Configure branding and URL White Listing (CORS) for that origin like any Hosted UI app.
  4. Copy clientId / clientSecret for this action app only.

Do not reuse your login portal’s clientId on the action page. The SDK checks hostedUiType from app-config; a Hosted Auth client on an action landing shows a wrong app / misconfigured door.

Employee/member access policy (allowSignup, groups) applies to Hosted Auth apps. Hosted Action apps do not use those portal fields.

App-config contract​

The SDK’s first call, POST /users/v1/hosted-auth/app-config, must identify the client as Hosted Action:

FieldWhereValues
hostedUiTypeTop-level or inside configHOSTED_AUTH | HOSTED_ACTION

When hostedUiType is HOSTED_ACTION, the sign-in step used before resolve:

  • Hides “Don’t have an account? Sign up”
  • Calls initiate with authAction: "auto" so users-ms can sign in existing users or create accounts without a separate sign-up screen

Until your environment returns hostedUiType, the SDK cannot infer Action mode from branding alone — ensure the portal app is Hosted Action and the API exposes the field.

SDK integration​

Wrap your action route with HostedUiProvider (same session BFF as Hosted Auth). Pass the Hosted Action clientId.

Covers identity proof when needed, deeplink resolve, access rules, and execution (KYC invite and related kinds):

import { HostedUiProvider, HostedInvite } from "@chainitservices/hosted-ui";

export function ActionLanding({ linkCode }: { linkCode: string }) {
return (
  <HostedUiProvider config={yourHostedConfig} embedLayout>
    <HostedInvite
      linkCode={linkCode}
      onComplete={({ accepted, taskId }) => {
        /* update your UI */
      }}
      onError={(err) => console.warn(err.message)}
    />
  </HostedUiProvider>
);
}

Read ?code= from the query string (or use readActionLinkCode() from the package when the SDK runs on that page).

Lower level: HostedActionShell​

Same pipeline as HostedInvite with optional props (onComplete, onDenied, linkCode). Use when you need shell-level callbacks without the HostedInvite wrapper.

KycInvite (invite UI only)​

KycInvite runs sign-in when needed, then the KYC invite consent UI. It does not run the full HostedActionShell resolve/access router. Prefer HostedInvite for standard email/SMS deeplink landings unless you intentionally own resolve and access yourself.

Custom resolve (advanced)​

Optional action on HostedUiConfiguration (HostedActionIntegrationConfig): override resolveActionContext, access checks, or completion hooks when your BFF owns resolve. Default behavior calls ChainIT’s deeplink resolve with the user access token.

Do not log or render deeplink payload in the DOM; keep resolved metadata in memory only.