Choose a starting project
Choose the smallest example that demonstrates your application's boundary. First get its login and protected request working; then replace the example's data and storage with your product's implementation.
Find a starting point for your app
| You are building… | Start here | Access needed |
|---|---|---|
| A new app using hosted identity | The service walkthroughs below | A Udibo account; template code has separate repository access |
| An existing app using hosted identity | Connect your application or plan a migration | A Udibo account |
| A local prototype or app-owned authentication | The public package examples below | No hosted account |
The walkthroughs show what you will build before you choose a template. If you want something runnable now without a hosted account, go straight to the package examples.
Explore the service walkthroughs
These guides explain how to assemble a product on the hosted service:
| Product shape | What you will learn |
|---|---|
| B2B SaaS | Organizations, a protected project list, organization-specific actions, and verified webhooks |
| Consumer app | Hosted account pages, profile claims, verified email, and records belonging to one user |
| Client portal | Per-document access, organization grants, and checks for a list of resources |
Two more cover services without a browser frontend: an API service that protects a JSON API and automates a grant report, and an MCP server whose tools are gated by the signed-in person's permissions in their organization.
These service templates are not publicly distributed. Each one is a Node.js 26 application on Hono with Postgres; the three browser templates add React Router. Read the walkthroughs as implementation guides. Use a public package example for a runnable starting point, or arrange access to the service templates with Udibo. A hosted account alone does not grant repository access.
The service templates are licensed MIT-0 (MIT No Attribution), so you can build
your product on one without crediting Udibo. Delete its LICENSE, or replace it
with your own if you plan to open-source your project; a private project needs
no license file.
Run a public package example
The package quickstart includes the clone, install, and run commands for a complete local Hono application. It needs Node.js 24.2 or later, pnpm, and Git, and does not need a hosted account, database, or email service.
The Hono external-auth example runs against a local provider by default. To connect it to your managed tenant, follow Use Udibo for issuer discovery, callback registration, identity scopes, and API validation. Replace the demo's explicit endpoints and scopes along with its issuer and credentials.
| Your project | Example or guide |
|---|---|
| Hono app that owns its authentication | Local Hono application |
| Hono app connecting to a separate issuer | Hono with external auth |
| An API without a frontend | Hono API service |
| A new React app that runs its own authentication | React Router template |
| An existing app using managed identity | Use Udibo |
The examples are development fixtures. In-memory stores reset on restart and demo credentials are public. Follow the example's instructions and the deployment guide before using it as the basis of a production app.
What the service templates expect
Complete application registration first. The browser-based B2B SaaS, consumer app, and client portal walkthroughs expect these server-side settings:
| Variable | Value |
|---|---|
UDIBO_ISSUER | Your tenant's trusted issuer origin |
APP_ORIGIN | This application's origin; its registered callback is {APP_ORIGIN}/auth/callback |
UDIBO_CLIENT_ID | The confidential application registration's ID |
UDIBO_CLIENT_SECRET | Its one-time client secret |
UDIBO_WEBHOOK_SECRET | B2B SaaS only: the secret for the endpoint at {APP_ORIGIN}/webhooks/udibo |
DATABASE_URL | The Postgres database the application stores its data and sessions in |
SESSION_SECRET | At least 32 bytes of entropy that encrypts sessions and sign-ins in progress; new,old rotates it |
PORT | Optional. Where the server listens; each walkthrough gives its default |
Each walkthrough describes how its template uses SESSION_SECRET and how to
rotate it.
Register the callback for the origin you actually run.
The MCP server and API service accept bearer tokens and have their own configuration. Follow their walkthroughs for the audience, client registration, and token setup.
The B2B and portal walkthroughs require the relevant organization, permission, and resource setup too. Complete those steps through the supported administrator workflow; do not embed an administrator's session in your application.
Make the example your own
Keep the authentication boundary while replacing the demonstration data. The service templates already keep sessions in Postgres; a package example keeps them in memory, so give it durable sessions and application storage. Preserve resource ownership checks, configure production callbacks and secrets, and test both successful and refused requests. A frontend route guard does not protect the API.
Next: Connect your first application, then prepare for production.
Last verified 2026-10-13.