Identity providers

An identity provider (IdP) is an external service Huudis can delegate authentication to. Two kinds are configurable per workspace:

• SAML — enterprise federation. Configure an IdP like Okta or Azure AD and Huudis becomes the service provider. Users at that customer get a "Sign in with Okta" button on your OIDC client's login page.
• OIDC — chain Huudis to an upstream OIDC provider. Less common; typically used when an enterprise insists their internal IdP is the source of truth.

For the built-in social providers (Google, Apple, Facebook) those are configured globally on a Huudis instance, not per-workspace — see Social providers.

All endpoints require a bearer admin JWT — see Authentication.

Endpoints

Method	Path	Purpose
GET	/v1/iam/identity-providers	List IdPs configured for the active workspace
POST	/v1/iam/identity-providers	Register a new IdP
PATCH	/v1/iam/identity-providers/:id	Update name or metadata
DELETE	/v1/iam/identity-providers/:id	Remove an IdP

Only owner and admin can mutate. Members get 403 FORBIDDEN.

List IdPs

GET /v1/iam/identity-providers

Response

{
  "data": [
    {
      "id": "idp_01KPG30…",
      "accountId": "acc_01KPG30…",
      "name": "Acme Okta",
      "type": "saml",
      "metadata": {
        "entityId": "http://www.okta.com/exk1abc…",
        "ssoUrl": "https://acme.okta.com/app/.../sso/saml",
        "certificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
        "attributeMapping": {
          "email": "NameID",
          "name": "DisplayName"
        }
      },
      "createdAt": "2026-04-12T10:00:00.000Z",
      "updatedAt": "2026-04-12T10:00:00.000Z"
    }
  ]
}

Register an IdP

POST /v1/iam/identity-providers

Request body

Field	Type	Required	Description
name	string (1–120)	yes	Display name shown to the user on the chooser. Must be unique within the workspace.
type	saml | oidc	yes	Protocol.
metadata	object	yes (effectively)	Protocol-specific configuration. See below.

SAML metadata shape

Key	Required	Description
entityId	yes	The IdP's entity ID (audience/issuer).
ssoUrl	yes	The IdP's SSO redirect URL.
certificate	yes	PEM-encoded X.509 certificate used to verify SAML assertions.
attributeMapping	no	Map of huudis-field → SAML attribute name. Common fields: email, name, locale. Defaults to NameID for email.

OIDC metadata shape

Key	Required	Description
issuer	yes	The IdP's OIDC issuer URL. Huudis discovers /.well-known/openid-configuration from it.
clientId	yes	Client ID Huudis is registered as on the upstream IdP.
clientSecret	yes	Stored encrypted at rest. Never returned in GET responses.
scope	no	Default openid profile email.

Response — 201 Created. The full IdP object.

Errors

Status	error.code	When
409	DUPLICATE_NAME	An IdP with that name already exists in this workspace.
400	INVALID_METADATA	Required keys missing or certificate doesn't parse.
400	NO_ACTIVE_WORKSPACE	Bearer token has no active workspace.

Update an IdP

PATCH /v1/iam/identity-providers/:id

Request body

Field	Description
name	Rename.
metadata	Replace the metadata blob. Send the full new shape; we don't deep-merge.

type is immutable — create a fresh IdP if you need to switch protocols.

Delete an IdP

DELETE /v1/iam/identity-providers/:id

Removes the configuration. Users who signed in via this IdP keep their usr_… and any consents, but new sign-ins through it are rejected.

204 No Content.

The identity provider object

Field	Type	Description
id	string (idp_…)	Stable ID.
accountId	string	Workspace this IdP belongs to.
name	string	Display name. Unique per workspace.
type	saml | oidc	Protocol.
metadata	object	Protocol config. OIDC clientSecret is redacted in GET responses.
createdAt, updatedAt	ISO 8601

How users land on a workspace's IdP

When a user starts an OIDC flow at /v1/oidc/authorize, Huudis decides which login methods to show:

1. The global social providers (Google, Apple, Facebook) that are enabled instance-wide.
2. Any IdPs registered for the workspace that owns the requested client.
3. Password sign-in (always available unless explicitly disabled).

If the OIDC client owns workspace acc_X, only workspace acc_X's IdPs are surfaced. This means an Acme Okta IdP doesn't leak to other customers' login screens.

SAML SP metadata

Huudis publishes its own SP metadata at https://huudis.com/api/v1/iam/saml/metadata?accountId={acc_…} — download it and hand to the IdP admin when they configure the relying-party application on their side.

The ACS (assertion consumer service) URL is https://huudis.com/api/v1/iam/saml/{accountId}/acs. The audience / entity ID matches that URL.

Just-in-time provisioning

When a user signs in via a workspace IdP for the first time:

• If the SAML assertion's email matches an existing usr_…, Huudis links the SAML identity to that user and proceeds.
• Otherwise Huudis provisions a new usr_… with email + name from the assertion. The user has no password — they can only sign in via SAML until they set one through their account settings.

Existing workspace members keep their existing role. Newly provisioned users land as member — SCIM-driven role provisioning isn't supported yet (it's on the backlog).

Events

No events are emitted for IdP CRUD. Audit-log entries (identity_provider_registered, identity_provider_updated, identity_provider_deleted) capture the same data.

Next

• Social providers — the instance-wide Google/Apple/Facebook config.
• OIDC clients — the apps that surface IdP buttons on their login screens.
• Users — per-workspace member management.