Getting Started

Zarejestruj apkę, wepnij SDK, ship.

Getting Started

Przejście end-to-end — od “mam apkę SvelteKit/Next.js/Laravel” do “userzy logują się przez WolfieAuth”. Wall-clock: 5–10 min jak kopiujesz-wklejasz, dłużej jak czytasz.

1. Zarejestruj swoją apkę w panelu WolfieAuth

Wejdź na auth.wolfieguard.com/admin/clients/new i wypełnij:

Pole	Co wpisać
Nazwa	Czytelne dla człowieka, np. “Acme CRM”
App slug	Krótka nazwa lowercase, np. `crm` — auto-prefiksuje się do `<twojOrgSlug>-crm` żeby dwie orgi mogły mieć “crm” bez kolizji
Redirect URIs	Gdzie WolfieAuth wysyła userów po loginie. SvelteKit/React: `https://twoja-apka.com/auth/callback`. Next.js Auth.js: `https://twoja-apka.com/api/auth/callback/wolfieauth`. WordPress: `https://twoja-strona.com/wp-admin/admin-ajax.php?action=wolfieauth_callback`. Perfex: `https://twoj-perfex.com/wolfieauth_client/callback`
Trusted	Włącz dla swoich apek żeby ekran consentu był skipowany przy każdym loginie. Wyłącz dla third-party
Owner org	Defaultuje do Twojej aktywnej org — org której Stripe Connect dostaje plan revenue

Dostaniesz clientId i clientSecret (pokazany RAZ — zapisz natychmiast). Dodaj do env Twojej apki:

WOLFIEAUTH_ISSUER=https://auth.wolfieguard.com
WOLFIEAUTH_CLIENT_ID=twojorgslug-crm
WOLFIEAUTH_CLIENT_SECRET=<z-panelu-admin>

2. Wybierz SaaS RBAC template

Większość apek pasuje do jednego z pięciu kanonicznych kształtów. Zastosuj w /admin/clients/<id>#users → Roles → 📋 Use template:

Template	Role	Dla czego
Solo	Owner	Personal tools, founder-only
B2B Team	Admin / Editor / Viewer	CRM, project mgmt
B2B Hierarchical	Admin / Billing-Admin / Editor / Auditor / Viewer	Księgowość, ERP
Marketplace	Vendor-Admin / Vendor-Staff / Customer	Multi-vendor stores
Internal Tool	Super-Admin / Tenant-Admin / Member / Auditor	Platform-owner + sub-tenants

Każda rola w permissions[] używa kanonicznych stringów typu members.invite / billing.read / plans.write. Twoja downstream apka czyta je z claims.wolfieauth_permissions[]. Mix and match — zastosuj template, potem dodaj custom rolę dla swojej niche need.

3. Wepnij SDK

Wybierz pasujący SDK ze strony SDKs. Przykład SvelteKit:

$ npm install @wolfieauth/sdk-sveltekit

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { createWolfieAuthHandle, pendingApprovalGate } from '@wolfieauth/sdk-sveltekit/server';

const auth = createWolfieAuthHandle({
  template: {
    id: 'guest-request',
    issuer:   process.env.WOLFIEAUTH_ISSUER!,
    clientId: process.env.WOLFIEAUTH_CLIENT_ID!,
    branding: { appName: 'Acme CRM' },
  },
  sessionSecret: process.env.SESSION_SECRET!,
});

export const handle = sequence(auth, pendingApprovalGate);

<!-- src/routes/auth/login/+page.svelte -->
<script>
  import { LoginPage } from '@wolfieauth/sdk-sveltekit/components';
  export let data;
</script>
<LoginPage config={data.loginConfig} />

To wszystko dla SvelteKit. Ten sam wzór dla Next.js / Express / Django / Laravel — patrz SDKs dla każdego.

4. Mirror user-a do DB Twojej apki

Każda apka potrzebuje lokalnych rzędów Organization + OrgMembership żeby jej query mogły FK-ować do org-id. Mirror dzieje się na pierwszym OIDC callbacku per (user × org) w SDK middleware:

const mirror: Handle = async ({ event, resolve }) => {
  const c = event.locals.session?.claims;
  if (!c) return resolve(event);

  const org = await prisma.organization.upsert({
    where:  { wolfieauthOrgId: c.wolfieauth_org_id },
    create: {
      name:            c.wolfieauth_org_name,
      type:            c.wolfieauth_org_tier === 'PLATFORM' ? 'SUPER' : 'CLIENT',
      wolfieauthOrgId: c.wolfieauth_org_id,
      wolfieauthSlug:  c.wolfieauth_org_slug,
    },
    update: { name: c.wolfieauth_org_name },
  });

  await prisma.orgMembership.upsert({
    where:  { userId_organizationId: { userId: c.sub, organizationId: org.id } },
    create: { userId: c.sub, organizationId: org.id, role: mapRole(c.wolfieauth_role_slug) },
    update: { role: mapRole(c.wolfieauth_role_slug) },
  });

  event.locals.org = org;
  return resolve(event);
};

Krytyczny invariant: Brak lokalnej tabeli User. WolfieAuth IS Twoja user-table. Zapisuj userId = sub wszędzie; refresh user details (name, email, avatar) z /userinfo gdy potrzebujesz, cache in-process ~5 min. Eliminuje całą klasę bugów ze stale-record.

5. Twoja apka czyta claims żeby gate-ować features

import { hasActiveFeature, isApproved } from '@wolfieauth/sdk-core/oidc/claims';

if (!isApproved(claims)) return redirect('/auth/pending');

if (hasActiveFeature(claims, 'twojorgslug-crm', 'ksef_enabled')) {
  // user ma feature KSeF na aktywnej org
}

Claim wolfieauth_features[] to flat tablica ["<appClientId>:<feature>", …] — hasFeature() sprawdza we wszystkich active sub-ach we wszystkich orgach (union mode), hasActiveFeature() filtruje tylko do aktualnie wybranej org-u (workspace mode). Wybierz model który pasuje.

Co dalej

SSO & Sesje żeby zrozumieć co się dzieje na każdym requeście
Plany & Billing żeby zacząć charge-ować
Admin dla Users tab, Comp overrides, Theme, MCP tokens

Ostatnia aktualizacja: 2026-05-01