Build a client portal

Availability: this walkthrough describes a service template currently available through beta repository access. It is not a public standalone starter. You can follow the same design in your own application using the first-login guide. For runnable public package examples, use starter projects.

Before you start

You need an accessible Udibo tenant, a development application configured as a confidential authorization-code client with refresh tokens, and a client secret. Choose opaque access tokens for these walkthroughs; they validate through introspection. See application registration for the exact settings.

The app requests openid profile email. Define application permissions in your tenant's permission catalog and assign roles separately; permission names are not additional OAuth scopes.

Set up the example

Register http://localhost:8009/auth/callback and configure:

If you have the template checkout, run deno task dev from templates/client-portal.

Define documents:read, documents:write, and documents:share in your permission catalog. Register the document and project resource types you use, and arrange initial resource grants through an administrator workflow. Permissions explains the resource and grant API shapes.

1. Ask about the document being accessed

A token cannot enumerate every document a person may access. The application gets candidate documents from its own data store and asks Udibo about those specific resources.

The list uses POST /api/check/batch: one set of checks for documents and another for their projects, chunked to the endpoint's limit of 100 candidates. It returns only documents allowed by the resulting decisions.

A direct read checks the same access boundary. Updating a document additionally requires documents:write. Keep the read and write decisions separate.

Checkpoint: a user granted one document sees that document and cannot read another by guessing its ID.

2. Model inheritance deliberately

Udibo does not store your application's document-to-project hierarchy. The portal knows that relationship, checks both resources, and accepts an appropriate grant on either.

A project grant therefore reaches its documents because the application applies that rule. It does not automatically reach arbitrary descendants in Udibo.

Checkpoint: grant a project and verify access to its documents, then confirm a different project's documents remain inaccessible.

3. Share with people or organizations

A resource grant can name a person or an organization. An organization grant resolves through accepted membership and can restrict which member roles may exercise it.

The active organization on a token is not a substitute for a resource check. An organization-scoped documents:read role does not by itself grant access to every document resource. Conversely, a person with a direct resource grant may have no permissions claim on their token and still be allowed to read it.

Checkpoint: test a direct recipient, an organization recipient, a member outside the grant's role restriction, and someone with a similarly named organization permission but no resource grant.

What sharing can do today

The example reads documents:share to decide who should be offered a sharing option. That application permission does not authorize a write to Udibo's tenant-management API.

Resource grants currently require an administrator workflow, and application machine tokens do not provide general tenant-management access. Account for that limitation before promising self-service sharing to your customers.

Replace the in-memory workspace with durable application data, preserve consistent responses for missing and inaccessible documents, and use the production checklist before launch.

Last verified 2026-09-06.