Kinde Directories API

openapi: 3.2.0
info:
  version: '1'
  title: Kinde Management Directories API
  description: 'Provides endpoints to manage your Kinde Businesses.


    ## Intro


    ## How to use


    1. Set up and authorize a machine-to-machine (M2M) application.


    2. Generate a test access token


    3. Test request any endpoint using the test token'
  termsOfService: https://docs.kinde.com/trust-center/agreements/terms-of-service/
  contact:
    name: Kinde Support Team
    email: support@kinde.com
    url: https://docs.kinde.com
servers:
- url: https://{subdomain}.kinde.com
  variables:
    subdomain:
      default: your_kinde_subdomain
      description: The subdomain generated for your business on Kinde.
tags:
- name: Directories
  x-displayName: Directories
paths:
  /api/v1/directories:
    servers: []
    get:
      tags:
      - Directories
      operationId: getDirectories
      summary: Get SCIM directories
      description: 'Returns a list of SCIM directories for your organization.


        read:scim_directories'
      parameters:
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 50 if parameter not sent.
        schema:
          type:
          - integer
          - 'null'
      - name: starting_after
        in: query
        description: The ID of the directory to start after.
        schema:
          type:
          - string
          - 'null'
      - name: organization_code
        in: query
        description: Filter by organization code to get directories for a specific organization.
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: SCIM directories successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_directories_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Directories
      operationId: createDirectory
      summary: Create SCIM directory
      description: 'Create a new SCIM directory for user and group synchronization.


        create:scim_directories'
      externalDocs:
        url: https://docs.kinde.com/developer-tools/scim-provisioning/
        description: SCIM Provisioning
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_code:
                  type: string
                  description: The organization code to create the SCIM directory for.
                  example: org_1ccfb819462
                directory_name:
                  type: string
                  description: A descriptive name for the SCIM directory.
                  example: Production Directory
                provider_code:
                  type: string
                  description: The SCIM provider code to use for this directory.
                  enum:
                  - entra_id_azure_ad
                  - okta
                  - google_workspace
                  - custom_scim_v2
                  - cyberark
                  - jumpcloud
                  - onelogin
                  - pingfederate
                  - rippling
                  example: entra_id_azure_ad
              required:
              - org_code
              - directory_name
              - provider_code
      responses:
        '201':
          description: SCIM directory successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_directory_response'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              examples:
                organization_required:
                  summary: Organization code required
                  value:
                    errors:
                    - code: ORGANIZATION_REQUIRED
                      message: Organization code is required
                      field: org_code
                directory_name_required:
                  summary: Directory name required
                  value:
                    errors:
                    - code: DIRECTORY_NAME_REQUIRED
                      message: Directory name is required
                      field: directory_name
                provider_code_required:
                  summary: Provider code required
                  value:
                    errors:
                    - code: PROVIDER_CODE_REQUIRED
                      message: Provider code is required
                      field: provider_code
                invalid_provider:
                  summary: Invalid provider code
                  value:
                    errors:
                    - code: INVALID_PROVIDER
                      message: Invalid or disabled provider code
                      field: provider_code
                organization_not_found:
                  summary: Organization not found
                  value:
                    errors:
                    - code: ORGANIZATION_NOT_FOUND
                      message: Organization not found
                      field: org_code
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          description: Conflict - Directory already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              examples:
                directory_exists:
                  summary: Directory already exists
                  value:
                    errors:
                    - code: DIRECTORY_EXISTS
                      message: A SCIM directory already exists for this organization
                      field: org_code
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/directories/{directory_id}:
    servers: []
    parameters:
    - name: directory_id
      in: path
      description: The directory's ID.
      required: true
      schema:
        type: string
        example: directory_0192b1941f125645fa15bf28a662a0b3
    get:
      tags:
      - Directories
      operationId: getDirectory
      summary: Get SCIM directory
      description: 'Retrieve SCIM directory details by ID.


        read:scim_directories'
      responses:
        '200':
          description: SCIM directory successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_directory_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    patch:
      tags:
      - Directories
      operationId: updateDirectory
      summary: Update SCIM directory
      description: Update SCIM directory configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                directory_name:
                  type: string
                  description: A descriptive name for the SCIM directory.
                  example: Updated Production Directory
              required:
              - directory_name
      responses:
        '200':
          description: SCIM directory successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_directory_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - Directories
      operationId: deleteDirectory
      summary: Delete SCIM directory
      description: 'Delete a SCIM directory and all associated data.


        delete:scim_directories'
      responses:
        '200':
          description: SCIM directory successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_directory_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
components:
  schemas:
    error_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    update_directory_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: DIRECTORY_UPDATED
        message:
          type: string
          description: Response message.
          example: SCIM directory updated successfully
        directory:
          $ref: '#/components/schemas/directory'
    not_found_response:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              example: ROUTE_NOT_FOUND
            message:
              type: string
              example: The requested API route does not exist
    create_directory_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: DIRECTORY_CREATED
        message:
          type: string
          description: Response message.
          example: SCIM directory created successfully
        directory:
          $ref: '#/components/schemas/directory'
    get_directory_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        directory:
          $ref: '#/components/schemas/directory'
    directory:
      type: object
      properties:
        id:
          type: string
          description: The unique ID for the SCIM directory.
          example: directory_0192b1941f125645fa15bf28a662a0b3
        directory_name:
          type: string
          description: The name of the SCIM directory.
          example: Production Directory
        directory_endpoint_id:
          type: string
          description: The endpoint ID for the SCIM directory.
          example: ksde_0192b1941f125645fa15bf28a662a0b3
        secret_token:
          type: string
          description: The secret token for SCIM authentication.
          example: kstkn_0192b1941f125645fa15bf28a662a0b3
        status:
          type: string
          description: The current status of the SCIM directory.
          enum:
          - Pending
          - Validating
          - Active
          - Inactive
          - Error
          example: Pending
        organization_code:
          type: string
          description: The organization code this directory belongs to.
          example: org_1ccfb819462
        last_sync_started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the last sync started.
          example: '2024-11-18T13:32:03+11'
        last_sync_completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the last sync completed.
          example: '2024-11-18T13:32:03+11'
        last_sync_error:
          type:
          - string
          - 'null'
          description: The last sync error message.
          example: Connection timeout
        created_on:
          type: string
          format: date-time
          description: When the directory was created.
          example: '2024-11-18T13:32:03+11'
    delete_directory_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: DIRECTORY_DELETED
        message:
          type: string
          description: Response message.
          example: SCIM directory deleted successfully
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
    get_directories_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        has_more:
          description: Whether more records exist.
          type: boolean
        directories:
          type: array
          items:
            $ref: '#/components/schemas/directory'
  responses:
    bad_request:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    too_many_requests:
      description: Too many requests. Request was throttled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    not_found:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/not_found_response'
    forbidden:
      description: Unauthorized - invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  securitySchemes:
    kindeBearerAuth:
      description: 'Requires an access token obtained using the client_credentials flow.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT