Docs/Start

Integrate an application

Add passkey registration, sign-in and short-lived verified claims without moving application authorization into RustyAuth.

Use the stable account UUID

Key downstream people and ownership records by the RustyAuth sub. Email, phone, profile names and credentials can all change.

Choose the right surface

Consumer	Protocol	Purpose
Browser	`HTTP/JSON + @rustyauth/client`	Passkey ceremonies and secure session cookie
Dioxus dashboard	`Connect + Protobuf`	Operator and Fleet commands with a browser session
Trusted service	`Native gRPC + Protobuf`	Scoped identity, events and management integration
Application API	`JWT + JWKS`	Local claim verification and application authorization

1. Run the local realm

scripts/local-stack standalone up

The launcher starts the public Dioxus surface, private backend and private SableDB. The public HTTP client lives in packages/client; complete examples live in examples.

2. Register a passkey

A trusted enrolment controller requests registration options, the browser calls navigator.credentials.create(), and RustyAuth verifies the response against server-side single-use ceremony state. For local evaluation, read the generated bootstrap value from .env.standalone.local.

import { createRustyAuthClient } from "@rustyauth/client";

const auth = createRustyAuthClient({ baseUrl: "http://localhost:8081" });

await auth.register({
  identifier: { type: "email", value: "[email protected]" },
  displayName: "Ada Lovelace",
  bootstrapToken: localDevelopmentToken,
});

Bootstrap is administrative

Never embed the bootstrap token in a production browser bundle. Replace local bootstrap registration with a reviewed invitation or provisioning boundary.

3. Sign in

The browser requests authentication options for a canonical email or E.164 phone, calls navigator.credentials.get() and submits the assertion. A successful response creates a Secure, HttpOnly, SameSite session cookie. JavaScript does not receive the durable session bearer value.

await auth.signIn({ type: "email", value: "[email protected]" });

4. Exchange and verify

Call POST /v1/token with the browser session to receive a short-lived ES256 access token. Keep it in memory. The downstream API verifies signature and policy locally against RustyAuth's JWKS.

GET /.well-known/jwks.json

Required checks:
  alg       == ES256
  iss       == configured public issuer
  aud       contains your API audience
  exp / nbf are valid with bounded clock skew
  tenant_id == expected isolated realm
  sub       is a valid RustyAuth account UUID

JWT verification proves authentication claims. Your API must still authorize the requested resource and action.

5. Handle lifecycle events

Use resumable event streaming from a trusted service for account and credential lifecycle work. Store the cursor durably and make consumers idempotent. Short-lived service-account tokens enforce events.read and, when a projector fetches the current safe profile, identity.read. Do not put private RPC credentials in browser code.

The authentication events guide includes working grpcurl commands, the signup-to-primary-database pattern, signed webhook verification, retry behavior and HTTP polling.

Production checklist

Use HTTPS and exact reviewed origins.
Provision the first Owner from a deployment shell.
Replace bootstrap enrolment with a trusted product flow.
Validate every JWT claim required by your policy.
Keep access tokens in memory and sessions in HttpOnly cookies.
Design account recovery and abuse controls before launch.
Run a clean-room restore drill and complete a real passkey sign-in.

Continue with the API boundary, identity data model and complete GitHub integration guide.