Kinde Search API

openapi: 3.2.0
info:
  version: '1'
  title: Kinde Management Search 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: Search
  x-displayName: Search
paths:
  /api/v1/search/users:
    servers: []
    get:
      tags:
      - Search
      operationId: searchUsers
      x-scope: read:users
      description: 'Search for users based on the provided query string. Set query to ''*'' to filter by other parameters only.

        The number of records to return at a time can be controlled using the `page_size` query string parameter.


        read:users'
      summary: Search users
      parameters:
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 10 if parameter not sent.
        schema:
          type:
          - integer
          - 'null'
      - name: query
        in: query
        description: Search the users by email or name. Use '*' to search all.
        schema:
          type:
          - string
          - 'null'
      - name: api_scopes
        in: query
        description: Search the users by api scopes.
        schema:
          type:
          - string
          - 'null'
      - name: properties
        in: query
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      - name: starting_after
        in: query
        description: The ID of the user to start after.
        schema:
          type:
          - string
          - 'null'
      - name: ending_before
        in: query
        description: The ID of the user to end before.
        schema:
          type:
          - string
          - 'null'
      - name: expand
        in: query
        description: 'Additional data to include in the response. One or more of (comma-separated): "organizations", "identities", "properties".'
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: Users successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_users_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
components:
  schemas:
    error_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    search_users_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
        message:
          type: string
          description: Response message.
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique ID of the user in Kinde.
                example: kp_0ba7c433e5d648cf992621ce99d42817
              provided_id:
                type:
                - string
                - 'null'
                description: External ID for user.
                example: U123456
              email:
                type:
                - string
                - 'null'
                description: Default email address of the user in Kinde.
                example: user@domain.com
              username:
                type:
                - string
                - 'null'
                description: Primary username of the user in Kinde.
                example: john.snow
              last_name:
                type: string
                description: User's last name.
                example: Snow
              first_name:
                type: string
                description: User's first name.
                example: John
              is_suspended:
                type: boolean
                description: Whether the user is currently suspended or not.
                example: true
              picture:
                type:
                - string
                - 'null'
                description: User's profile picture URL.
                example: https://example.com/john_snow.jpg
              total_sign_ins:
                type:
                - integer
                - 'null'
                description: Total number of user sign ins.
                example: 1
              failed_sign_ins:
                type:
                - integer
                - 'null'
                description: Number of consecutive failed user sign ins.
                example: 0
              last_signed_in:
                type:
                - string
                - 'null'
                description: Last sign in date in ISO 8601 format.
                example: '2025-02-12T18:02:23.614638+00:00'
              created_on:
                type:
                - string
                - 'null'
                description: Date of user creation in ISO 8601 format.
                example: '2025-02-12T18:02:23.614638+00:00'
              organizations:
                type: array
                description: Array of organizations a user belongs to.
                items:
                  type: string
              identities:
                type: array
                description: Array of identities belonging to the user.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    identity:
                      type: string
              properties:
                type: object
                description: The user properties.
                additionalProperties:
                  type: string
              api_scopes:
                type: array
                description: Array of api scopes belonging to the user.
                items:
                  type: object
                  properties:
                    org_code:
                      type: string
                    scope:
                      type: string
                    api_id:
                      type: string
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
  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'
    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