Skip to main content
POST
/
orgs
/
{org_id}
/
identity-providers
cURL
curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/identity-providers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider_key": "acme",
  "allowed_domains": [
    "<string>"
  ],
  "client_id": "<string>",
  "client_secret": "<string>",
  "default_role_id": 123,
  "display_name": "<string>",
  "enabled": true,
  "groups_claim": "<string>",
  "issuer": "https://acme.okta.com",
  "scopes": "<string>"
}
'
{
  "allowed_domains": [
    "<string>"
  ],
  "client_secret_set": true,
  "created_at": 123,
  "enabled": true,
  "enforced": true,
  "id": "<string>",
  "kind": "<string>",
  "org_id": "<string>",
  "provider_key": "<string>",
  "updated_at": 123,
  "client_id": "<string>",
  "default_role_id": "<string>",
  "display_name": "<string>",
  "groups_claim": "<string>",
  "issuer": "<string>",
  "scopes": "<string>"
}

Authorizations

​
Authorization
string
header
required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Path Parameters

​
org_id
string
required

Body

application/json

Create an OIDC identity-provider connection for an org.

​
provider_key
string
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.

Example:

"acme"

​
allowed_domains
string[]

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

​
client_id
string | null

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

​
client_secret
string | null

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

​
default_role_id
integer<int64> | null

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_name
string | null

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

​
enabled
boolean | null

Whether the connection is active. Defaults to true.

​
groups_claim
string | null

Claim carrying group membership. Defaults to groups.

​
issuer
string | null

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

Example:

"https://acme.okta.com"

​
kind
null | enum<string>

Connection kind. Defaults to oidc (backward-compatible). Use directory for a login-less SCIM connection: no issuer/client creds required, it only anchors SCIM group→role mappings + the catch-all role.

Available options:
oidc,
saml,
directory
​
scopes
string | null

Space-separated scopes. Defaults to openid email profile.

Response

Connection created

Masked view of a connection. Never includes the client secret.

​
allowed_domains
string[]
required
​
client_secret_set
boolean
required

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

​
created_at
integer<int64>
required
​
enabled
boolean
required
​
enforced
boolean
required

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

​
id
string
required
​
kind
string
required
​
org_id
string
required
​
provider_key
string
required
​
updated_at
integer<int64>
required
​
client_id
string | null

OIDC client id. null for non-OIDC kinds.

​
default_role_id
string | null

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

​
display_name
string | null
​
groups_claim
string | null
​
issuer
string | null

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

​
scopes
string | null