Onboarding Flows

Use this page when you need to choose the right first-run path for a new customer, operator, or end user.

Use this page when

• You need to choose the right first-run path for a new customer, operator, or end user.
• You are planning which onboarding flow applies to a specific persona (admin, developer, end user, knowledge owner).
• You want to verify that onboarding is complete across all required surfaces.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Choose the right flow

Starting point	Best for	Main outcome
Console sign-in	Invited users, SSO users, admins	Confirm org context and reach the main operating surface
Chat-first sign-in	End users who start from the chat or tasks workbench	Redirect to console sign-in and return to the requested workspace
Admin workspace setup	First org admin or sole active user	Create the first agent deployment and reach a chat-ready state
Non-admin setup request	Team members who need chat before an admin has deployed anything	Request setup and wait for an eligible runtime
Application integration	Developers connecting an app to a managed agent gateway	Create an Access Key and send the first governed request
Hosted gateway bootstrap	Operators bringing up a runtime in their own environment	Create a Gateway Key, install kt, and register the hosted gateway
Knowledge base setup	Knowledge owners curating agent context	Review the auto-populated org-context knowledge base, customize it, create additional assets, and bind them to agents for runtime recall
Connector setup	Integration leads connecting Google Drive	Authorize a Google Drive OAuth connector
Team and RBAC setup	Org admins onboarding multiple teams	Create teams, assign roles, configure SSO, and allocate wallets

Workflow map

Flow 1: Console-first access

Use this flow when the customer starts from the Keeptrusts console.

1. Open the console URL provided by your deployment team.
2. Sign in with one of these supported methods:
   • Email and password
   • SSO (OIDC or SAML)
   • Passkey, if your organization has enabled it
3. Confirm the environment, organization name, and role shown in the console shell.
4. Open Overview, Events, and Gateways to make sure the workspace matches what your team expects.

This flow is complete when the user can confirm they are in the right organization and can open the main operating pages without permission surprises.

Flow 2: Chat-first sign-in redirect

Use this flow when the user starts on the chat workbench before they are signed in.

1. Open the chat or tasks workbench while signed out.
2. Keeptrusts redirects the browser to the console sign-in flow.
3. The login URL includes a returnTo parameter for the workspace that was requested.
4. After successful sign-in, the console returns the browser to the requested chat or tasks workspace.
5. If the workspace is already ready, the user can continue immediately from the authenticated surface. If no eligible agent deployment exists yet, Keeptrusts shows the setup or request flow instead of opening a workbench with an empty agent selector.

What the user should expect:

• The requested workspace path is preserved during the redirect.
• The browser does not receive the upstream API bearer token.
• The workbench opens only after sign-in completes.

This flow is complete when the user lands back in the requested workspace with a valid authenticated session.

Flow 3: First admin setup in chat

Use this flow when the first org admin or sole active user reaches chat or tasks and no eligible agent deployment exists yet.

1. Start from chat after sign-in.
2. When prompted, choose whether the first deployment should target the hosted gateway or a hosted gateway.
3. Select a starter template.
4. Provide the provider credentials needed for the first deployment.
5. Set the default agent name.
6. Click Deploy and continue to chat.

What Keeptrusts creates during this flow:

• A configuration entity
• A configuration version
• An agent identity
• A deployment bound to the selected runtime target

This flow is complete when chat transitions into a chat-ready state and the user can send their first governed prompt.

Flow 4: Non-admin request setup

Use this flow when a team member needs chat but no eligible deployment exists and they are not allowed to self-setup.

1. Start from chat after sign-in.
2. Complete the Request setup form.
3. Include the preferred target, providers, models, and any note the admin needs.
4. Submit the request.
5. Wait for an admin to create the required deployment.
6. Refresh status from chat and continue once the runtime becomes available.

This flow is complete when the user sees a chat-ready workspace without having to create infrastructure or provider credentials themselves.

Flow 5: Application integration with Access Keys

Use this flow when a developer wants to send requests through a managed agent gateway.

1. Go to Settings → Access Keys.
2. Create an Access Key and copy the revealed value.
3. Point your OpenAI-compatible or Anthropic-compatible client at the Keeptrusts gateway URL instead of the upstream model provider.
4. Send a test request.
5. Confirm the request appears in Events, Usage, or the related gateway usage view.

Use this flow for application traffic. Do not use Gateway Keys for end-user request traffic.

Flow 6: Hosted gateway bootstrap with Gateway Keys

Use this flow when your team runs the kt gateway in its own environment.

1. Go to Settings → Gateway Keys.
2. Create a Gateway Key and copy the revealed value.
3. Install the kt CLI on the target host.
4. Export the Keeptrusts API URL, the Gateway Key, and the configuration identifier.
5. Run kt gateway run.
6. Open Gateways in the console and confirm the runtime appears as connected.

Use this flow for runtime authentication only. Gateway Keys authenticate hosted gateway runtimes, not customer application requests.

Signs onboarding is complete

You can treat onboarding as complete when all of the following are true:

• Users can sign in with the expected identity flow.
• The correct organization and role context is visible.
• At least one governed request has been sent successfully.
• Events and usage surfaces show the new activity.
• The team knows whether it is using Access Keys, Gateway Keys, or both.
• Ownership for policy changes, escalations, and evidence exports is clear.
• Knowledge assets are curated and bound to agents (if knowledge grounding is needed).
• External connectors are authorized and bound (if tool access is needed).
• Team structure, roles, and wallet allocations are configured (if multi-team).

Flow 7: Knowledge base setup

Use this flow when you want agents to draw on curated context at runtime.

1. Navigate to Knowledge Base in the console.
2. Click Create asset and choose a kind: Static (markdown), Upload (file), or Git Sync (repository-backed).
3. Author or upload the initial content.
4. Promote the asset through the lifecycle: draft → in_review (enterprise) → active.
5. Go to the Bindings tab and bind the asset to the target agent.
6. Send a governed request through that agent.
7. Confirm the knowledge was recalled — check the citation record in the event detail.

This flow is complete when an active knowledge asset is bound to an agent and confirmed as recalled during a governed request.

Flow 8: Connector setup

Use this flow when agents need governed access to external tools and data sources.

1. Navigate to Connectors in the console.
2. Click Add connector and choose Google Drive.
3. Complete the Google OAuth authorization flow.
4. Click Refresh capabilities to discover available tools and resources.
5. Add a binding to the target agent.
6. Verify the connector status shows active and capabilities are populated.

This flow is complete when the connector is authorized, capabilities are discovered, and a binding exists to the target agent.

Flow 9: Team and RBAC setup

Use this flow when your organization needs structured access control before opening the platform to multiple teams.

1. Open Settings → Members & Teams.
2. Create teams that match your organizational structure.
3. Invite members and assign roles: owner, admin, member, or viewer.
4. Configure SSO (OIDC or SAML) if your organization uses an identity provider.
5. Enable MFA or passkeys in Security Settings for additional protection.
6. Allocate wallet credits to each team from the organization wallet.
7. Verify each team member can access only the resources and pages their role permits.

This flow is complete when every team member has the right role, scope, and wallet allocation.

For AI systems

• Canonical terms: Keeptrusts onboarding flows, console sign-in, chat-first sign-in, admin setup, Access Keys, Gateway Keys, knowledge base setup, connector setup, team RBAC setup.
• Flows covered: console-first access, chat-first sign-in redirect, first admin setup, non-admin request setup, application integration (Access Keys), hosted gateway bootstrap (Gateway Keys), knowledge base setup, connector setup, team and RBAC setup.
• Related pages: Quickstart, Authentication Flows, Access Keys & Gateway Keys, Knowledge Base, Connectors, Members, Teams and Roles.

For engineers

• Console-first access is complete when the user can confirm their organization and role without permission errors.
• Chat-first entry redirects to /login with returnTo preserved so the user lands back in the requested workspace after authentication.
• Application integration uses Access Keys (not Gateway Keys) — point the client SDK at the Keeptrusts gateway URL instead of the upstream provider.
• Hosted gateway bootstrap requires: Gateway Key, kt CLI installed, KEEPTRUSTS_API_URL and KEEPTRUSTS_GATEWAY_TOKEN exported, then kt gateway run.
• Verify onboarding completion by checking that events appear in the Events page and usage shows the new activity.

For leaders

• Use this page to select the onboarding path that matches each persona in your organization — not all users need the same flow.
• Admin setup creates infrastructure (configurations, agents, deployments); non-admin setup requests are gated behind admin approval, preserving governance.
• Team and RBAC setup (Flow 9) should be completed before broadly inviting users to prevent unintended access.
• Onboarding is incomplete until ownership for policy changes, escalations, and evidence exports is documented and assigned.

Next steps

• Quickstart
• Authentication Flows
• Customer Journeys
• Access Keys & Gateway Keys
• Gateways & Actions
• Knowledge Base
• Connectors
• Members, Teams and Roles
• Security Settings
• Wallets