Skip to main content

Documentation Index

Fetch the complete documentation index at: https://setup.despia.com/llms.txt

Use this file to discover all available pages before exploring further.

Native Clerk authentication for iOS and Android. The host app embeds Clerk’s native SDK, your web app drives it from JavaScript through despia() calls and two global hooks. Optional, for apps that need Keychain or Keystore backed sessions, native Sign in with Apple, offline cold-launch, or zero-config server-side auth. Web auth providers like Supabase, Firebase, NextAuth, Auth0, or Clerk’s own web SDK work in Despia out of the box without this.
Requires iOS 17 or Android API 24, and a publishable key from your Clerk Dashboard.

​
Installation

npm install despia-native

import despia from 'despia-native';

​
How it works

The bridge exposes two globals on window. You define window.onClerkEvent to receive every event, the bridge writes window.clerkJWT with the current session token and auto-refreshes it every 50 seconds.
GlobalTypeLifecycle
window.onClerkEvent(payload) => voidYou define. Receives every event.
window.clerkJWT`stringnull`Bridge writes. Auto-refreshed every 50s. null when signed out.
Wire the listener first, then configure the bridge. Events are not buffered, a handler attached after a command was issued will miss the result. 
const isDespia = navigator.userAgent.toLowerCase().includes('despia')

if (isDespia) {
    window.onClerkEvent = (r) => {
        if (!r.ok) {
            console.error(r.event, r.error.code, r.error.message)
            return
        }

        if (r.event === 'ready') {
            despia('clerk://state')
        }

        if (r.event === 'state') {
            if (r.isSignedIn) {
                renderApp(r.user)
            } else {
                despia('clerk://authview')
            }
        }
    }

    despia('clerk://configure?key=pk_test_abc123')
}
Every event has the same envelope: 
{
    ok: boolean,                                // false means error present
    event: string,                              // 'ready', 'state', 'signIn', etc.
    status?: string,                            // success detail
    error?: { code: string, message: string },  // when ok === false
    // plus route-specific fields
}

​
Configure

Initialize the bridge with your Clerk publishable key on every page load. Same-key calls re-emit ready as a no-op. Different keys switch tenant and clear the secure session store. 
despia('clerk://configure?key=pk_test_abc123')
Emits: 
{
    "ok": true,
    "event": "ready",
    "status": "configured",
    "publishableKey": "pk_test_abc123"
}
status is configured, already_configured, or reconfigured. Errors emit with event: "configure": invalid_key, reconfigure_in_progress, reconfigure_failed, unsupported_os, sdk_not_linked.

​
Next

Auth Methods

Auth Sheet, password, OAuth, Apple, email code, phone code, passkeys, MFA, SSO.

Sessions

Read who’s signed in and the auto-refreshed JWT.

Backend

Next.js and TanStack authenticated on first paint.

Account

User Profile, sign-out, attribution, multi-tenant.

Reference

Events, status values, error codes, quirks.

​
Resources

NPM Package

despia-native

Support

support@despia.com