orgs

Changed on

Create an SSO or directory identity connection for the organization.

post/orgs/{org_id}/identity-providers

Request

  • Base URL
    https://api.timbal.ai
  • URL
    https://api.timbal.ai/orgs/{org_id}/identity-providers
  • Auth
    HTTP bearer

Path parameters

org_idstring required

Request body

allowed_domainsstring[]

Email domains eligible for JIT auto-provisioning. Empty = no JIT.

client_idstring nullable

OAuth client id registered with the IdP. Required for oidc.

client_secretstring nullable

OAuth client secret. Sealed at rest with the org DEK; never returned. Required for oidc.

default_role_idinteger nullable

Optional catch-all role for JIT members whose group claim matched no mapping. When omitted, such members are added with no role (a bare member, pending an admin grant) rather than an implicit default. Accepts a number or a stringified id (2227 or "2227").

display_namestring nullable

Human-readable label for the login button / admin UI.

enabledboolean nullable

Whether the connection is active. Defaults to true.

groups_claimstring nullable

Claim carrying group membership. Defaults to groups.

issuerstring nullable

IdP issuer / discovery base; /.well-known/openid-configuration is fetched from here. Required for oidc; ignored for directory.

kind'oidc' | 'saml' | 'directory'

Which provider implementation drives a connection's login flow. Mirrors the kind CHECK in db/init.sql; widened additively as kinds ship (oidc first, saml later).

provider_keystring required

Stable, URL-safe handle used in the login URL (/auth/sso/{provider_key}) and the signed OAuth state. Lowercase letters/digits/hyphens; must not collide with the built-in social providers. Globally unique.

scopesstring nullable

Space-separated scopes. Defaults to openid email profile.

Example request

{
  "issuer": "https://acme.okta.com",
  "provider_key": "acme"
}

Response

Connection created

allowed_domainsstring[] required
client_idstring nullable

OIDC client id. null for non-OIDC kinds.

client_secret_setboolean required

Whether a client secret is configured. The secret itself is never returned.

created_atinteger required
default_role_idstring nullable

Catch-all role granted to JIT members with no matching group mapping. null = no catch-all role.

display_namestring nullable
enabledboolean required
enforcedboolean required

Read-only here: SSO enforcement isn't configurable via the API yet.

groups_claimstring nullable
idstring required
issuerstring nullable

OIDC issuer. null for non-OIDC kinds (e.g. SAML), whose connection details live in kind-specific fields added when those kinds ship.

kindstring required
org_idstring required
provider_keystring required
scopesstring nullable
updated_atinteger required

Changes