Authentication

Your application’s users reach your GenUI Portal project through short-lived session tokens. Authentication is how your backend turns one private secret key into a session token for each person who uses your application.

What it is

Two things work together.

• A secret key is a private credential that belongs to a single project. Only your backend holds it. It should never be compiled into a frontend application (web, native, or desktop) or stored anywhere on a user’s device.
• A session token stands for one person’s session with your project. Your backend mints one by presenting the secret key, and the token expires 30 minutes later. It records who the person is, or that they are anonymous, and which project it is for.

Each organization has its own endpoint for minting tokens. Your backend mints them at your organization’s endpoint, and a secret key only works at the endpoint of the organization it belongs to. A key presented anywhere else is turned away.

To be specific: a session token is bound to one organization and one project. Each organization verifies against its own keys, so a token created for organization A is refused for organization B. A token also names the single project it was created for, and your project should only accept tokens created for it, so a token for project A does not work for project B.

How to use it

The flow is three steps, all on your backend.

1. Create a secret key for your project and store it somewhere safe. You are shown the key only once. If you lose it, rotate it (see below).
2. Mint a session token with the project’s secret key when a person starts using your app. Your backend sends the key to your organization’s endpoint in the GenUI Portal, along with which user is signed in (a user ID of your choosing, or anonymous). The GenUI Portal returns a session token that expires in 30 minutes.
3. Use the session token for that person’s requests to your project’s endpoint in the GenUI Portal. When it expires, mint another one. The backend SDK wraps these calls for Dart and Node.

To replace a project’s secret key, rotate it. You get a new one, and the old key keeps working for 24 hours so you can move your backend over without downtime. After that the old key is refused when minting new session tokens.

IMPORTANT: Secret key and token operations are not exposed to agents through the MCP server.

Failure modes

• Minting a token fails. The secret key is wrong, it was rotated more than 24 hours ago, or it is being used at a different organization’s endpoint than the one it belongs to. Check the key and the endpoint.
• Too many anonymous tokens. Anonymous token creation is capped for each project. People who are signed in are not capped.
• A rotated key stopped working. Its 24-hour grace has passed. Move your backend to the new key.