Cladior · OAuth

OAuth Flow

When a Cladior user opens your product for the first time, the SDK presents a consent screen. Once accepted, a session token is minted and stored. On every return visit the token is restored automatically. Your backend receives a verified user identity with no additional work.

01

The consent screen

The first time a user opens your product, CladiorSDK.init() detects that no session exists for this app. It opens the Cladior consent overlay, which shows the user:

  • Your app name and icon
  • The rate per kilobyte they will be charged
  • The scopes your app has requested (see Scopes)

The user must be signed in to Cladior and have a funded wallet to proceed. If either condition is missing, the overlay prompts them to sign in or top up before continuing.

02

Token handshake

When the user accepts, the SDK calls POST /oauth/authorize on the Cladior API. This creates a user_apps record and mints a session token scoped to the (user, app) pair.

The session token is returned to the SDK and stored in localStorage under cladior_session_{appId}. It is not a Supabase JWT and does not expire on its own. It is revoked server-side when the user disconnects the app.

Security note. The session token is a random UUID. It proves the user accepted this specific app at the stored rate. It is scoped to one (user, app) pair and cannot be used against other apps.
03

Session restore on return visits

On every subsequent page load, CladiorSDK.init() reads the stored session token and validates it against the proxy. If the token is valid and unrevoked, the SDK enters the ready state immediately with no consent screen.

Your onReady callback fires with the user's identity. Proxy requests authenticated with the token start billing immediately.

CladiorSDK.init({
  appId: 'your-app-id',
  onReady: (user) => {
    console.log('Signed in as', user.displayName);
  },
  onDisconnect: () => {
    // session revoked or token expired
  },
});
04

Re-authorization

If a user revokes access from their Cladior dashboard, the token is invalidated server-side. The next proxy request returns 401 and the SDK fires onDisconnect. Calling CladiorSDK.connect() re-opens the consent screen and mints a new session token.

Re-authorization always shows the current rate. If you have changed your rate since the user last accepted, the new rate is displayed and must be accepted again.

← SDK Reference Scopes →