Connecting users

Link an end user to their Fleeex wallet up front, with no chat call and no 402.

getConnection() lets you check whether the configured (app, user) is linked to a Fleeex wallet and funded, without provoking a 402 on a first chat call, and hands back an onboarding link to open.

const { connected, funded, connectUrl } = await client.getConnection();
 
if (!connected || !funded) {
  redirect(connectUrl); // sign in → authorize the app → top up
}

It returns a ConnectionStatus:

Unlike the proxy and getBalance(), getConnection() never raises a 402. It always returns the status. connectUrl is the same signed onboarding link a 402 would hand back, minted on demand with no chat call and no charge.

What happens at connectUrl

Fleeex hosts that page; your app hands the user over and gets them back. Three things happen there, and the middle one is worth knowing about:

1. The user signs in to their own Fleeex account, because the wallet is theirs rather than your app's.
2. They authorize your app by name. The page states which app is asking and the monthly ceiling it will be allowed to spend, and the user has to acknowledge that name. Fleeex checks the acknowledgement server-side against the app the link actually names.
3. They fund the wallet, if it needs it.

That consent step exists because an onboarding link is minted on the data plane, for a user id the calling app chooses, so anyone who can register an app could mint one and send it to someone else. Naming the app, and verifying the name, is what keeps a forwarded link from binding someone else's app to the wallet of whoever clicks it.

Two consequences for your integration:

• Register a name your users will recognize. It is the name they are asked to consent to, and an unrecognizable one is a step they'll abandon. It's the name you set when registering the app.
• You never send that acknowledgement yourself. It belongs to the signed-in user's own session on the Fleeex page, so the 403 APP_CONSENT_MISMATCH behind it is not an error your app can receive. An API key cannot reach that route at all.

The user can later revoke your app, and a revoked mapping is deliberately indistinguishable from one that never existed: connected reads false and a chat call answers the generic 402. Neither says access was withdrawn. See the error reference.

Returning the user to your app

Pass a redirectUri to have Fleeex send the user back once they're connected and funded:

const { connected, funded, connectUrl } = await client.getConnection({
  redirectUri: "https://app.example.com/fleeex/return",
});

The redirectUri must exactly match one of your app's registered redirect URIs (managed on your app), or the call fails with a 400 (FleeexApiError). This is a security guard against open redirects.

When to use it

• Onboarding: connect a user the first time they open an AI feature, instead of waiting for the first call to fail.
• Gating UI: show a "Connect Fleeex" state when connected or funded is false, without spending anything to find out.