Client sign-in

For your own script or service, use a developer token. It needs no browser callback or refresh flow.

Use client sign-in when each person must connect their own Fluso account to a supported client. Fluso handles sign-in in the browser. Your client receives a one-use code and exchanges it for tokens.

A new client needs a configured Fluso callback. Contact support before implementing that integration. These endpoints do not register arbitrary callback URLs.

Open Fluso sign-in

Your client requests a sign-in URL. Open it in the user's browser.

Let the user sign in

Fluso handles sign-in and returns a one-use code through your configured callback.

Exchange the code for tokens

Your client sends the code with its private proof. Fluso returns tokens for API access and session renewal.

The proof, called PKCE, keeps another client from using the returned code. Generate it once for each sign-in attempt.

Use auth.access_token as Authorization: Bearer TOKEN for API requests. Save auth.refresh_token privately for renewal. auth.expires_in tells you when the access token expires.

Implement the sign-in exchange (Node.js)

Use Node 22 or later. Set baseUrl to your Cloud API URL, including /v1. Use your configured client name. Set clientUserId to the user's stable ID within your client.

Generate the proof and request the browser URL:

import { randomBytes, createHash } from 'node:crypto';

const baseUrl = 'https://api.fluso.ai/v1';
const client = 'YOUR_CONFIGURED_CLIENT';
const clientUserId = 'YOUR_CLIENT_USER_ID';

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const start = await fetch(`${baseUrl}/auth/client/start`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client, client_user_id: clientUserId, code_challenge: challenge,
  }),
});
if (!start.ok) throw new Error(`Sign-in could not start (${start.status})`);
const { url } = await start.json();

Open url in the user's browser. Keep verifier on the initiating client. Do not log it or send it to the callback URL.

After the configured callback returns code, exchange it using the same client identity and verifier:

const exchange = await fetch(`${baseUrl}/auth/client/exchange`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client, client_user_id: clientUserId, code, code_verifier: verifier,
  }),
});
if (!exchange.ok) throw new Error(`Sign-in exchange failed (${exchange.status})`);
const { auth } = await exchange.json();

Store auth in the client's credential store. It includes access_token, refresh_token, expires_in, session_id, and user.

The browser step calls POST /v1/auth/client/complete with the returned state under the user's Clerk app session. Current browser callbacks support configured Fluso handoffs, including Telegram. A developer token cannot perform that browser step.

Sign-in state expires after ten minutes. The returned code expires after five minutes and works once. If the exchange response is lost, start sign-in again.

For another language, generate a verifier with 43 to 128 ASCII letters, digits, or -._~. Its challenge is SHA-256 encoded as unpadded base64url.

Keep the session active

Before the access token expires, send the saved refresh token to POST /v1/auth/client/refresh:

{
  "refresh_token": "YOUR_SAVED_REFRESH_TOKEN"
}

The response contains replacement access_token and refresh_token values. Save both together before sending further requests. Allow only one refresh at a time for that session.

Recover a lost refresh response

Retry the same refresh token within 30 seconds to recover the same replacement pair. Reusing it after that window revokes the session.

Refresh extends the session's 30-day expiry. If refresh is rejected, ask the user to sign in again. Do not create a new session for each API request.

Sign out

Send the refresh-token body above to POST /v1/auth/client/revoke. Remove the local credentials after revocation.

Client-session endpoint reference

Method and path	Required credential and use
`POST /v1/auth/client/start`	PKCE challenge. Request the browser URL.
`POST /v1/auth/client/complete`	Clerk app session and returned state. Issue the one-use code.
`POST /v1/auth/client/exchange`	Code, client identity, and original verifier. Issue tokens.
`POST /v1/auth/client/sessions`	Clerk app session. Create a client session for an already signed-in app.
`GET /v1/auth/client/sessions`	Clerk app session. List up to 100 active sessions, newest first.
`DELETE /v1/auth/client/sessions/{session_id}`	Clerk session for any owned session, or a client token for itself.
`POST /v1/auth/client/refresh`	Refresh token. Rotate the token pair.
`POST /v1/auth/client/revoke`	Refresh token. Revoke its session. Returns 204 even if already invalid.

Client tokens cannot manage developer tokens. That operation requires Clerk sign-in.

Your deployment's schema lists exact identifier constraints and response fields.

Client sign-in

Sign in once

Keep the session active

Sign out

On this page