Kinde Directories API

openapi: 3.0.0
info:
  version: '1'
  title: Kinde Account API Keys Directories API
  description: '

    Provides endpoints to operate on an authenticated user.


    ## Intro


    ## How to use


    1. Get a user access token - this can be obtained when a user signs in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc).


    2. Call one of the endpoints below using the user access token in the Authorization header as a Bearer token. Typically, you can use the `getToken` command in the relevant SDK.

    '
  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
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.\n\n<div>\n  <code>read:scim_directories</code>\n</div>\n"
      parameters:
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 50 if parameter not sent.
        schema:
          type: integer
          nullable: true
      - name: starting_after
        in: query
        description: The ID of the directory to start after.
        schema:
          type: string
          nullable: true
      - name: organization_code
        in: query
        description: Filter by organization code to get directories for a specific organization.
        schema:
          type: string
          nullable: true
      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.\n\n<div>\n  <code>create:scim_directories</code>\n</div>\n"
      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.\n\n<div>\n  <code>read:scim_directories</code>\n</div>\n"
      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.\n\n<div>\n  <code>delete:scim_directories</code>\n</div>\n"
      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:
  responses:
    bad_request:
      description: Invalid request.
      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'
    too_many_requests:
      description: Too many requests. Request was throttled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  schemas:
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
    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
    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'
    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_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    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_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'
    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
          format: date-time
          description: When the last sync started.
          example: '2024-11-18T13:32:03+11'
          nullable: true
        last_sync_completed_at:
          type: string
          format: date-time
          description: When the last sync completed.
          example: '2024-11-18T13:32:03+11'
          nullable: true
        last_sync_error:
          type: string
          description: The last sync error message.
          example: Connection timeout
          nullable: true
        created_on:
          type: string
          format: date-time
          description: When the directory was created.
          example: '2024-11-18T13:32:03+11'
  securitySchemes:
    kindeBearerAuth:
      description: 'To access these endpoints, you will need to use a user token. This can be obtained when your users sign in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc). Find this using the getToken command in the relevant SDK.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT