Connecting your application

Connect is where you wire your own application to a GenUI Portal project. It gives you the organization and project IDs your applications point at, the secret key your backend application mints session tokens with, etc.

What it is

Three pieces do the work:

• The organization and project IDs point your applications at the right place. Your backend application mints session tokens at your organization’s endpoint, which the organization ID names, and your frontend application sends the project ID on every turn to say which project it is talking to. Connect shows both.
• A secret key is the private credential your backend application mints project-specific session tokens with. It belongs to this one project, and it never leaves your backend. Connect creates, lists, and rotates the project’s keys, and shows a new key once. See Authentication for how keys and session tokens fit together.
• The allowlist is the set of web origins and native application bundle IDs allowed to reach the project. It sits on top of the session token: the token proves who a user is, and the allowlist stops a token from being replayed from a website or native application you did not build. A new project starts with http://localhost so local development works, and you add your origins before launch.

How to use it

Wiring an application is a backend job and a frontend job. Your backend application holds the project’s secret key and mints session tokens. Your frontend application sends turns and renders what comes back.

1. Look up the organization ID and the project ID from the top of the Connect page in the dashboard. Your backend and frontend applications will need them.
2. Create a secret key and store it somewhere only your backend application can read. You are shown it once. If you lose it, rotate the key for a new one, and the old one keeps working for 24 hours while you move over.
3. When a person starts using your frontend application, your backend should mint a session token. The Connect page has the specific steps, and Authentication covers how keys and session tokens work in depth.
4. Add your production origins and bundle IDs to the allowlist before you launch. An origin is where your frontend web application is served, such as https://app.example.com. A bundle ID names a native application, such as com.example.app.
5. Render turns in your frontend application. Send the session token and the project ID with each turn, and draw what the platform returns. When a turn fails it returns one of the error codes below, and your frontend owns how each one looks to the user.

Failure modes

A failing turn returns one coarse code and nothing about the cause. The detail stays on the platform, in Logs, so that no one can use the error response to probe your safety configuration. Your frontend decides what each code shows a user.

• unauthorized covers three cases that look the same from outside: the session token is missing, it has expired, or the request came from an origin or bundle ID the allowlist does not include. Re-minting the token fixes the first two and never fixes the third, so your client should retry once and then stop rather than mint tokens in a loop.
• blocked means a guardrail stopped the turn. Which guardrail, and why, stays on the platform on purpose. Show the user a safe message and move on.
• no_result means the turn produced nothing to render. Fall back to your static experience.
• invalid_output means the model returned output that was not valid for your catalog. It is a fault on our side, not yours, and often clears on a retry; fall back in the meantime.
• invalid_action means a tap sent an action that does not match anything served on the conversation. It usually means a stale screen or a hand-built request, and sending the same action again fails the same way.
• unavailable means the platform could not serve the turn. It is usually transient, so retry later and fall back in the meantime.
• unsupported_version means your client and the project share no compatible version. Update your client, or pin a version the project still serves.

Two more show up while you are wiring things.

• Minting a token fails. The secret key is wrong, it was rotated more than 24 hours ago, or it is being sent to a different organization’s endpoint than the one it belongs to. Check the key and the endpoint on Connect.
• Turns fail with unauthorized from a working token. The origin or bundle ID your frontend application runs on is not on the allowlist. Add it on Connect.