ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streamingCatentioAgent runtime
Huudis Docs
⌘K

Concepts

Huudis is small on purpose. Once you understand the seven objects below, you understand the whole system.

Account

An account is the top-level billing and ownership unit. One account can have many members. Account IDs look like acc_01KPG30SQTDDZ469FGR7DBE0DC — a ULID with an acc_ prefix.

Most personal users only ever see one account; teams may create more (one per organisation they belong to). Accounts also carry an enabledServices list — the set of Forjio products this account has opted into. See Service opt-in.

Workspace

A workspace is the configuration boundary inside an account. OIDC clients, identity providers, IAM policies, audit logs, and webhook subscriptions are all scoped to one workspace at a time.

Most accounts have a single workspace named after the account itself. You only need a second workspace if you want strict isolation between, say, your staging and production environments.

Workspace IDs look like ws_01KPG40SQT….

User

A user is a person (or service) with credentials in Huudis. Users belong to accounts via account_member rows. A user's primary identifier is their email, but the durable ID is usr_01KPG….

There are two kinds of users:

  • Workspace member — can administer the Huudis workspace itself (add OIDC clients, edit IAM, etc.). Authenticates against the Huudis dashboard via cookie session.
  • End user — a person who signed into one of your OIDC clients. Doesn't have a Huudis dashboard login — they only ever see Huudis through your app's login screen. Visible at End users in the dashboard.

The same usr_… ID can be both, depending on which OIDC clients they've authorised.

OIDC client

An OIDC client is an app (web, mobile, CLI, or service) registered to authenticate users via Huudis. Each client has:

  • A public client_id (e.g., oc_…).
  • A confidential client_secret (for confidential clients) — never sent to the browser.
  • One or more redirect_uris Huudis is allowed to send users back to.
  • A set of allowed grant types — typically authorization_code and refresh_token, plus device_code for CLIs.

A first-party Forjio product (Plugipay, Storlaunch, etc.) is an OIDC client too. Yours is no different from theirs.

Identity provider

An identity provider is an external service that Huudis can delegate authentication to — Google, Apple, Facebook. When configured, sign-in screens show a button for each provider; the user clicks it, authenticates on the provider's site, and Huudis links the resulting identity to a usr_….

Identity providers are configured at the workspace level. See Social providers.

Session

A session represents one signed-in user-agent (browser, mobile app, CLI). Sessions are backed by a refresh token; when the access token expires, the SDK exchanges the refresh token for a new access token (and a new refresh token — rotation).

Sessions show up in the dashboard at Dashboard → End users → [user] → Sessions. Revoking a session immediately invalidates its refresh token; subsequent access-token expiry will force the user back through sign-in.

MFA factor

A multi-factor authentication factor is a second credential a user has enrolled to prove identity beyond their password. Huudis supports:

  • TOTP — time-based codes from Google Authenticator, 1Password, Authy, etc.
  • WebAuthn — platform passkeys (Touch ID, Windows Hello) and roaming authenticators (YubiKey).

A user can enrol multiple factors and use any of them at sign-in. If MFA is required by an IAM policy (forjio:MfaPresent), a session that hasn't passed MFA cannot perform the gated action.

Putting it together

A typical flow:

  1. A new user lands on myapp.com, clicks Sign in with Huudis.
  2. The app redirects them to Huudis with client_id=oc_myapp.
  3. Huudis creates a new account + user, sends an email-verification link, and (after verify) signs the user in via the user's chosen method — password, Google, Apple.
  4. Huudis redirects back to myapp.com/callback?code=….
  5. The app exchanges the code for an access token + refresh token, stores the refresh token, and creates its own session for this user.
  6. Six hours later, the access token expires. The app uses the refresh token to silently mint a new one. The user notices nothing.

Next