Quickstart

In about ten minutes you'll have:

1. Signed up for a Huudis workspace.
2. Registered an OIDC client for your app.
3. Signed a real user in and exchanged the authorization code for an access token.

If you'd rather read about the model first, jump to Concepts. If you'd rather install the SDK first, see Installation.

Prerequisites

You'll need:

• A working email address — sign-up requires verification.
• About ten minutes.
• A local app you can point at Huudis with a redirect URI (e.g., http://localhost:3000/callback). It doesn't need to be deployed.

1. Sign up for a workspace

Head to huudis.com and click Sign up.

1. Enter your email and choose a password (10+ characters).
2. Click the verification link we send you.

If you'd rather sign up with Google, Apple, or Facebook, those buttons appear on the sign-up screen when the corresponding identity provider is wired into the Huudis instance you're using. See Social providers.

Once you're verified, you land in your first workspace's dashboard.

Workspaces are how Huudis isolates configuration. You get one workspace by default. Each workspace owns its own OIDC clients, identity providers, IAM policies, audit log, and team members. Most teams stay on a single workspace forever.

2. Register an OIDC client

In the dashboard, navigate to OIDC clients (or go directly to /dashboard/oidc-clients).

Click New client. Give it:

• Name — something human-readable like "My App Dev".
• Redirect URI — where Huudis sends users back after they sign in. For local development, http://localhost:3000/callback is fine. You can add more later.
• Allowed grant types — leave the defaults (authorization_code, refresh_token) unless you know you need device flow.

Huudis shows the client ID and client secret on the next screen. The secret is shown once — copy both into your terminal as environment variables:

export HUUDIS_CLIENT_ID=oc_xxxxxxxxxxxxxxxxxxxx
export HUUDIS_CLIENT_SECRET=ocs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat the client secret like a password. Anyone with HUUDIS_CLIENT_SECRET can exchange authorization codes and mint tokens on behalf of your app. We never display it again after creation. If you lose it, rotate the secret from the portal.

3. Sign a user in

The simplest end-to-end flow is the OIDC authorization code flow with PKCE: your app redirects the user to Huudis, Huudis authenticates them, Huudis redirects back with a one-time code, your backend exchanges the code for tokens.

Redirect the user to Huudis

Build the authorize URL on your backend, then redirect the browser:

https://huudis.com/api/v1/oidc/authorize
  ?response_type=code
  &client_id=oc_xxxxxxxxxxxxxxxxxxxx
  &redirect_uri=http://localhost:3000/callback
  &scope=openid%20profile%20email
  &state=<random-csrf-token>
  &code_challenge=<sha256(code_verifier) base64url>
  &code_challenge_method=S256

The user logs in (or, if they're already signed in to Huudis, skips straight through). Huudis redirects to http://localhost:3000/callback?code=…&state=….

Exchange the code for tokens

On your callback handler:

curl -X POST https://huudis.com/api/v1/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<code from query string>" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "client_id=$HUUDIS_CLIENT_ID" \
  -d "client_secret=$HUUDIS_CLIENT_SECRET" \
  -d "code_verifier=<the PKCE verifier you generated>"

The response contains an access_token, id_token, and refresh_token. You're done.

Easier: use the SDK

The SDKs handle PKCE, state, and token exchange for you. With the Node SDK:

import { HuudisClient } from '@forjio/huudis-node';

const huudis = new HuudisClient({
  clientId: process.env.HUUDIS_CLIENT_ID,
  clientSecret: process.env.HUUDIS_CLIENT_SECRET,
  redirectUri: 'http://localhost:3000/callback',
});

// 1. Redirect to authorize URL
const { url, codeVerifier, state } = huudis.oidc.buildAuthorizeUrl({
  scope: 'openid profile email',
});
// save codeVerifier + state in the user's session
res.redirect(url);

// 2. In your callback handler
const tokens = await huudis.oidc.exchangeCode({
  code: req.query.code,
  codeVerifier: storedVerifier,
});

// tokens.accessToken, tokens.idToken, tokens.refreshToken

4. Verify it worked

Check the dashboard at Dashboard → End users. You should see your test user listed with their email and the OIDC client they signed in to.

Or call the userinfo endpoint with the access token:

curl https://huudis.com/api/v1/oidc/userinfo \
  -H "Authorization: Bearer <access_token>"

You did it — you've signed your first Huudis user in.

What's next

• Installation — install the SDK properly for your project.
• Concepts — understand the model behind accounts, workspaces, users, and clients.
• OIDC overview — the full picture of authorization code, device flow, and refresh-token rotation.
• API reference — every admin endpoint.