ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streamingCatentioAgent runtime
Huudis Docs
⌘K

SDK overview

Huudis ships official SDKs for Node.js, Python, and Go. The three SDKs share an API shape so switching between languages is mostly mechanical.

Each SDK exposes two surfaces:

  1. HuudisClient — an object for performing OIDC flows and calling admin endpoints on a user's behalf.
  2. Verification helpers — verifyAccessToken (JWT verify with JWKS caching) and verifyWebhookSignature (HMAC-SHA256 of webhook bodies).

This page is a quick tour. Per-language details and reference docs are coming in a future release; for now, the package READMEs on npm/PyPI/GitHub are the source of truth.

Install

Language Command
Node.js npm install @forjio/huudis-node
Python pip install huudis
Go go get github.com/hachimi-cat/huudis-go

See Installation for prerequisites.

Construct a client

Node.js:

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

const huudis = new HuudisClient({
  baseUrl: 'https://huudis.com',
  clientId: process.env.HUUDIS_CLIENT_ID,
  clientSecret: process.env.HUUDIS_CLIENT_SECRET,
  redirectUri: 'https://myapp.com/callback',
});

Python:

from huudis import HuudisClient

huudis = HuudisClient(
    base_url="https://huudis.com",
    client_id=os.environ["HUUDIS_CLIENT_ID"],
    client_secret=os.environ["HUUDIS_CLIENT_SECRET"],
    redirect_uri="https://myapp.com/callback",
)

Go:

import huudis "github.com/hachimi-cat/huudis-go"

client, err := huudis.NewClient(huudis.ClientOptions{
    BaseURL:      "https://huudis.com",
    ClientID:     os.Getenv("HUUDIS_CLIENT_ID"),
    ClientSecret: os.Getenv("HUUDIS_CLIENT_SECRET"),
    RedirectURI:  "https://myapp.com/callback",
})

OIDC sign-in

Every SDK exposes the same three methods for the OIDC dance:

  • buildAuthorizeUrl({ scope, state? }) — returns { url, codeVerifier, state }. Redirect the browser to url; persist codeVerifier + state in the user's session.
  • exchangeCode({ code, codeVerifier }) — in your callback handler, returns { accessToken, idToken, refreshToken, expiresIn }.
  • refreshTokens({ refreshToken }) — mint a new access + refresh token. The SDKs single-flight this internally so two concurrent calls don't trigger reuse-detection.

Verify tokens

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

const claims = await verifyAccessToken(token, {
  jwksUrl: 'https://huudis.com/.well-known/jwks.json',
  audience: process.env.HUUDIS_CLIENT_ID,
});

Same shape in Python (verify_access_token) and Go (huudis.VerifyAccessToken). JWKS is cached in-process; the cache TTL respects the Cache-Control header from Huudis.

Verify webhook signatures

When Huudis posts an event to your subscribed endpoint, it includes X-Huudis-Signature: t=<unix>,v1=<hex>. Verify with the raw request body bytes — parsed JSON will round-trip with different whitespace and the HMAC will never match:

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

app.post('/webhooks/huudis', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyWebhookSignature(
    req.body,                                // raw Buffer
    req.header('X-Huudis-Signature') ?? '',
    process.env.HUUDIS_WEBHOOK_SECRET,
  );
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString('utf8'));
  // handle event...
  res.sendStatus(204);
});

Same in Python and Go — see the README for each package.

Admin operations

The client object exposes typed methods for every admin endpoint:

// List your registered OIDC clients
const clients = await huudis.oidcClients.list();

// Create a new client
const created = await huudis.oidcClients.create({
  name: 'My App',
  redirectUris: ['https://myapp.com/callback'],
});

// Rotate the secret
const rotated = await huudis.oidcClients.rotateSecret(created.id);

// List end users who signed into one of your clients
const users = await huudis.endUsers.list({ limit: 50 });

The Python and Go versions follow language-idiomatic naming (huudis.oidc_clients.list(), client.OIDCClients.List(ctx)).

What's coming

The full per-language guides (separate pages for Node.js, Python, Go with reference tables for every method) are coming. For now:

Next