Authentication

Entity Auth provides password auth with short‑lived access tokens and a refresh token. Web clients receive the refresh token as an HTTP‑only cookie; native clients (Swift) receive it in the response and store it in Keychain.

Install and set up (web)

import { EntityAuthClient } from "@/packages/sdk/src";

// Optional: pass baseURL if your API is not same‑origin
export const ea = new EntityAuthClient({ baseURL: process.env.NEXT_PUBLIC_API_URL });

Swift apps use the built‑in singleton:

import EntityKit

let ea = EntityAuth.shared
ea.updateBaseURL("https://your-api.example")

Register

await ea.register({ email: "user@example.com", password: "hunter2", tenantId: "t1" });

try await EntityAuth.shared.register(email: "user@example.com", password: "hunter2", tenantId: "t1")

Login

Send tenantId. The SDK will set the access token for subsequent authenticated calls.

const out = await ea.login({ email: "user@example.com", password: "hunter2", tenantId: "t1" });
// out = { accessToken, userId, sessionId } (web)

let ea = EntityAuth.shared
try await ea.login(email: "user@example.com", password: "hunter2", tenantId: "t1")
// ea.accessToken, ea.sessionId, ea.userId are populated and realtime watchers start

Access and refresh

• Access tokens expire after ~5 minutes.
• Web: the refresh token is set as ea_refresh cookie automatically on login.
• Native: the refresh token is returned by the API; the Swift SDK stores it in Keychain.

Refresh

Web requests made through ea.fetch() auto‑refresh on 401. You can also refresh manually:

await ea.refresh();

try await EntityAuth.shared.refresh()

Logout

await ea.logout();

await EntityAuth.shared.logout()

Recommended flow