ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streamingCatentioAgent runtime
Huudis Docs
⌘K

API overview

The Huudis admin API is a thin REST surface over the same operations the dashboard performs. Anything you can do as a workspace administrator in the dashboard, you can do via the API.

The OIDC endpoints (/oidc/authorize, /oidc/token, /oidc/userinfo, /.well-known/*) are documented on the OIDC overview page — those are user-facing and follow the OIDC spec rather than Huudis conventions.

Base URL

https://huudis.com/api/v1

Every endpoint on this page is relative to that base.

Conventions

Authentication

Admin endpoints require a bearer access token issued to your account:

Authorization: Bearer <access-token>

The full authentication picture (where the token comes from, scopes, refresh) is on the Authentication page.

Response envelope

Every JSON response uses the standard Forjio envelope:

{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_01KPG…",
    "timestamp": "2026-05-12T03:14:00.000Z"
  }
}

On error, data is null and error is populated:

{
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "redirect_uri is required",
    "field": "redirect_uri"
  },
  "meta": { ... }
}

Standard error codes: INVALID_REQUEST (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), RATE_LIMITED (429), INTERNAL (500).

Identifiers

Every resource has a typed prefix:

Prefix Type
acc_ Account
ws_ Workspace
usr_ User
oc_ OIDC client
ocs_ OIDC client secret
idp_ Identity provider config
pol_ IAM policy
grp_ IAM group
sess_ Session
fct_ MFA factor
evt_ Webhook event

All IDs after the prefix are ULIDs.

Pagination

List endpoints return cursor-paginated results:

GET /api/v1/oidc-clients?limit=50&cursor=oc_01KPG…

Response:

{
  "data": [ { ... }, { ... } ],
  "meta": {
    "cursor": "oc_01KPH…",
    "hasMore": true
  }
}

When hasMore is false, you've reached the end. Default limit is 25, max 100.

Rate limits

Admin API requests are rate-limited per access token:

  • 600 requests per minute rolling window.
  • 20 requests per second burst.

Rate-limited responses return 429 RATE_LIMITED with a Retry-After header.

OIDC endpoints have separate, more generous limits — see OIDC overview.

Endpoint groups

The admin API is organised by what each group of endpoints manages:

Group Path prefix Manages
Account /account/* Account profile, members, enabled services.
Workspaces /workspaces/* Workspace list and metadata.
OIDC clients /oidc-clients/* Client CRUD, secret rotation.
Identity providers /identity-providers/* Google/Apple/Facebook config.
IAM /iam/* Policies, groups, attachments, authz check.
End users /ops/end-users/* Users who signed into your clients.
MFA /mfa/* Enrolment and verification.
Webhook subscriptions /account/webhook-subscriptions/* Event delivery.
Audit log /account/audit-log Read-only audit feed.

What the API doesn't expose

Some operations are deliberately dashboard-only:

  • Initial workspace creation — happens during sign-up; can't be scripted.
  • Reading the client secret after creation — only on the rotate response. Lost secrets must be rotated.
  • Reading user passwords or password hashes — ever. Reset is the only path.

Next