> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Identity Provider

> Create an SSO or directory identity connection for the organization.



## OpenAPI

````yaml POST /orgs/{org_id}/identity-providers
openapi: 3.1.0
info:
  title: Timbal Platform API
  description: Public API documentation for the Timbal platform
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.timbal.ai
    description: Production
  - url: https://api.dev.timbal.ai
    description: Development
security: []
tags:
  - name: ace
    description: Action Control Engine (ACE) operations
  - name: analytics
    description: Project analytics
  - name: billing
    description: Subscriptions, usage, and payment-related operations
  - name: content
    description: Re-sign stored content URLs
  - name: files
    description: File operations
  - name: iam
    description: IAM — actions, roles, users, and authorization introspection
  - name: k2
    description: Knowledge Bases v2 operations
  - name: orgs
    description: Organization operations
  - name: projects
    description: Project operations
  - name: runs
    description: Execution operations
  - name: templates
    description: Public project template catalog
  - name: users
    description: Authenticated user profile
paths:
  /orgs/{org_id}/identity-providers:
    post:
      tags:
        - orgs
      description: Create an SSO or directory identity connection for the organization.
      operationId: handler
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityProviderReqBody'
        required: true
      responses:
        '201':
          description: Connection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProviderView'
        '409':
          description: provider_key already in use
      security:
        - bearer_auth: []
components:
  schemas:
    CreateIdentityProviderReqBody:
      type: object
      description: Create an OIDC identity-provider connection for an org.
      required:
        - provider_key
      properties:
        allowed_domains:
          type: array
          items:
            type: string
          description: Email domains eligible for JIT auto-provisioning. Empty = no JIT.
        client_id:
          type:
            - string
            - 'null'
          description: OAuth client id registered with the IdP. Required for `oidc`.
        client_secret:
          type:
            - string
            - 'null'
          description: >-
            OAuth client secret. Sealed at rest with the org DEK; never
            returned.

            Required for `oidc`.
        default_role_id:
          type:
            - integer
            - 'null'
          format: int64
          description: |-
            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:
          type:
            - string
            - 'null'
          description: Human-readable label for the login button / admin UI.
        enabled:
          type:
            - boolean
            - 'null'
          description: Whether the connection is active. Defaults to true.
        groups_claim:
          type:
            - string
            - 'null'
          description: Claim carrying group membership. Defaults to `groups`.
        issuer:
          type:
            - string
            - 'null'
          description: |-
            IdP issuer / discovery base; `/.well-known/openid-configuration` is
            fetched from here. **Required for `oidc`; ignored for `directory`.**
          example: https://acme.okta.com
        kind:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/IdentityProviderKind'
              description: >-
                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.
        provider_key:
          type: string
          description: |-
            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
        scopes:
          type:
            - string
            - 'null'
          description: Space-separated scopes. Defaults to `openid email profile`.
    IdentityProviderView:
      type: object
      description: Masked view of a connection. Never includes the client secret.
      required:
        - id
        - org_id
        - kind
        - provider_key
        - allowed_domains
        - client_secret_set
        - enabled
        - enforced
        - created_at
        - updated_at
      properties:
        allowed_domains:
          type: array
          items:
            type: string
        client_id:
          type:
            - string
            - 'null'
          description: OIDC client id. `null` for non-OIDC kinds.
        client_secret_set:
          type: boolean
          description: |-
            Whether a client secret is configured. The secret itself is never
            returned.
        created_at:
          type: integer
          format: int64
        default_role_id:
          type:
            - string
            - 'null'
          description: >-
            Catch-all role granted to JIT members with no matching group
            mapping.

            `null` = no catch-all role.
        display_name:
          type:
            - string
            - 'null'
        enabled:
          type: boolean
        enforced:
          type: boolean
          description: 'Read-only here: SSO enforcement isn''t configurable via the API yet.'
        groups_claim:
          type:
            - string
            - 'null'
        id:
          type: string
        issuer:
          type:
            - string
            - 'null'
          description: |-
            OIDC issuer. `null` for non-OIDC kinds (e.g. SAML), whose connection
            details live in kind-specific fields added when those kinds ship.
        kind:
          type: string
        org_id:
          type: string
        provider_key:
          type: string
        scopes:
          type:
            - string
            - 'null'
        updated_at:
          type: integer
          format: int64
    IdentityProviderKind:
      type: string
      description: >-
        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).
      enum:
        - oidc
        - saml
        - directory
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: >-
        Timbal API key. Obtain your API key from the Timbal platform settings.
        See [Authentication](/api-reference/authentication) for more
        information.

````