Hosted Auth

Hosted auth is the recommended way to let end users sign in to Candle from your app. Your app opens the Candle web flow, Candle handles Sign in with Apple and passkey unlock on candle.fi, and the SDK receives an app-scoped grant package for API calls.

Flow

Register your app as a public OAuth client in the Candle dashboard.
Add your redirect URI or universal/app link callback to the Candle app settings.
Launch hosted auth with PKCE from your app.
Candle signs the user in, asks for consent, unlocks the user's passkey-backed privacy material, and returns an app grant to your callback.
Store the returned grant package in secure storage and use it for Candle API calls.

Native/mobile clients must not embed a client secret. Use the app's client ID and PKCE for hosted auth. Client secrets are only for server-side customer operations.

Redirect URIs are enforced exactly. Add every callback your beta app uses, including custom schemes such as myapp://candle-auth, Android app links, iOS universal links, and local development callbacks.

SDK Usage

The SDK can generate the PKCE verifier and encrypted grant-package key for you, then finish the callback by exchanging the OAuth code and storing the app-scoped grant package.

React Native

const request = candle.makeHostedAuthorizationRequest({
  redirectUri: 'myapp://candle-auth',
})

await openURL(request.url)

// In your deep-link handler:
await candle.completeHostedAuthorization(callbackUrl)

Swift

let request = try Candle.Client.shared.makeHostedAuthorizationRequest(
  redirectURI: "myapp://candle-auth"
)

openURL(request.url)

// In your callback handler:
try await Candle.Client.shared.completeHostedAuthorization(request: request, callbackURL: url)

Kotlin

val request = Candle.Client.shared.makeHostedAuthorizationRequest(
  redirectUri = "myapp://candle-auth",
)

startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(request.url)))

// In your callback handler:
Candle.Client.shared.completeHostedAuthorization(request, callbackUrl)

iOS Entitlements

Hosted auth does not require the host app to enable Candle-managed Sign in with Apple or passkey capabilities. Passkeys are created and unlocked on candle.fi in the browser, so customer apps do not need to be added to Candle's AASA file. Your app only needs whatever callback registration its own redirect URI uses, such as a custom URL scheme or its own universal link domain.

User Identity

Candle accounts are global across customer apps. The hosted web flow verifies Apple tokens against Candle's web Services ID, then authorizes each customer app through an app grant. Passkeys use a Candle-generated opaque WebAuthn user handle, not your client ID, bundle ID, or the Apple sub.

Billing Portal

Users can manage their individual Candle plan at /account. The account portal uses the same hosted Apple identity and candle.fi passkey flow, then opens Stripe checkout or the Stripe billing portal for Plus and Pro plans.