5‑Minute Quickstart

This guide gets you from zero to authenticated in 5 minutes on Web and Swift. It includes exact steps and copy‑paste code blocks.

Before you start

Create a workspace in the dashboard, copy the generated .env snippet, and keep the default localhost origins (3000/3001/5173/4200) for local development.

Web (TypeScript/JavaScript)

1. Install SDK

npm install @entityauth/auth-client

2. Add environment variables

# copy from dashboard → Setup tab
ENTITY_AUTH_WORKSPACE_TENANT_ID=ws_prod_123
NEXT_PUBLIC_ENTITY_AUTH_WORKSPACE_TENANT_ID=ws_prod_123
NEXT_PUBLIC_ENTITY_AUTH_URL=https://ws_prod_123.entity-auth.com

3. Initialize SDK (tenant from env, not forms)

import { EntityAuthClient, init as initEA } from '@entityauth/auth-client';

initEA({
  workspaceTenantId: process.env.NEXT_PUBLIC_ENTITY_AUTH_WORKSPACE_TENANT_ID!,
  baseURL: process.env.NEXT_PUBLIC_ENTITY_AUTH_URL,
});

const ea = new EntityAuthClient({
  baseURL: process.env.NEXT_PUBLIC_ENTITY_AUTH_URL,
});

await ea.register({ email: 'user@example.com', password: 'password123' });

const { accessToken, userId, sessionId } = await ea.login({
  email: 'user@example.com',
  password: 'password123',
});

5. Protected request (auto‑refresh on 401)

const res = await ea.fetch('/api/user/me', { method: 'GET' });
const me = await res.json();
console.log(me);

6. Organizations (generic model)

import { SDK } from '@entityauth/auth-client';

// Create org via generic entities
const me = await SDK.me();
const org = await SDK.createEntity({
  workspaceTenantId: me.workspaceTenantId!,
  kind: 'org',
  properties: { name: 'Acme', slug: 'acme', ownerId: me.id }
});

// Link membership via generic relations
await SDK.linkRelation({
  workspaceTenantId: me.workspaceTenantId!,
  srcId: me.id,
  relation: 'member_of',
  dstId: org.id,
  attrs: { role: 'owner' }
});

Cross-origin web apps

Manage allowed origins per workspace in the dashboard. Localhost origins are pre-seeded; add production domains before deploying.

Swift (iOS/macOS)

Important: Convex Swift Dependency

EntityKit uses a forked version of convex-swift (github.com/entityauth/convex-swift). If you already have the official Convex package (github.com/get-convex/convex-swift), you must:

Remove the official get-convex/convex-swift from your Package.swift dependencies
Replace it with https://github.com/entityauth/convex-swift.git
Add EntityKit (which will use the forked convex-swift transitively)

This fork includes Entity Auth-specific realtime features. Xcode will show a package identity conflict error if both versions are present.

1. Add package

In Package.swift:

.package(url: "https://github.com/entityauth/EntityKit.git", from: "1.0.0")

2. Import and initialize

import EntityKit
let facade = EntityAuthFacade(
    config: EntityAuthConfig(
        environment: .production,
        workspaceTenantId: "YOUR_TENANT_ID"
    )
)

try await facade.register(request: RegisterRequest(
    email: "user@example.com",
    password: "password123",
    workspaceTenantId: "YOUR_TENANT_ID"
))

try await facade.login(request: LoginRequest(
    email: "user@example.com",
    password: "password123",
    workspaceTenantId: "YOUR_TENANT_ID"
))

let snapshot = facade.currentSnapshot()
print(snapshot.userId ?? "anonymous")

4. Protected request

struct Me: Decodable { let id: String; let email: String? }
let result: Me = try await facade.fetchGraphQL(
    query: """
    query Viewer { me { id email } }
    """,
    variables: nil
)

5. Organizations (create and switch)

let orgs = try await facade.organizations()
if let first = orgs.first {
    try await facade.switchOrg(orgId: first.orgId)
}

Next steps

Explore API via ea.getOpenAPI()