Kinde APIs API

openapi: 3.2.0
info:
  version: '1'
  title: Kinde Management APIs 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: APIs
  x-displayName: APIs
paths:
  /api/v1/apis:
    servers: []
    get:
      tags:
      - APIs
      operationId: getAPIs
      x-scope: read:apis
      summary: Get APIs
      description: 'Returns a list of your APIs. The APIs are returned sorted by name.


        read:apis'
      parameters:
      - name: expand
        in: query
        description: 'Additional data to include in the response. Allowed value: "scopes".'
        required: false
        schema:
          type:
          - string
          - 'null'
          enum:
          - scopes
      responses:
        '200':
          description: A list of APIs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_apis_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - APIs
      operationId: addAPIs
      x-scope: create:apis
      summary: Create API
      description: 'Register a new API. For more information read Register and manage APIs.


        create:apis'
      externalDocs:
        url: https://docs.kinde.com/developer-tools/your-apis/register-manage-apis
        description: Register and manage APIs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the API. (1-64 characters).
                  example: Example API
                audience:
                  type: string
                  description: A unique identifier for the API - commonly the URL. This value will be used as the `audience` parameter in authorization claims. (1-64 characters)
                  example: https://api.example.com
              required:
              - name
              - audience
      responses:
        '200':
          description: APIs successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_apis_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/apis/{api_id}:
    servers: []
    parameters:
    - $ref: '#/components/parameters/api_id'
    get:
      tags:
      - APIs
      operationId: getAPI
      x-scope: read:apis
      summary: Get API
      description: 'Retrieve API details by ID.


        read:apis'
      responses:
        '200':
          description: API successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - APIs
      operationId: deleteAPI
      x-scope: delete:apis
      summary: Delete API
      description: 'Delete an API you previously created.


        delete:apis'
      responses:
        '200':
          description: API successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_api_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/apis/{api_id}/scopes:
    servers: []
    get:
      tags:
      - APIs
      operationId: getAPIScopes
      x-scope: read:api_scopes
      summary: Get API scopes
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      description: 'Retrieve API scopes by API ID.


        read:api_scopes'
      responses:
        '200':
          description: API scopes successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_scopes_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - APIs
      operationId: addAPIScope
      x-scope: create:api_scopes
      summary: Create API scope
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      description: 'Create a new API scope.


        create:api_scopes'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  description: The key reference for the scope (1-64 characters, no white space).
                  example: read:logs
                description:
                  type: string
                  description: Description of the api scope purpose.
                  example: Scope for reading logs.
              required:
              - key
      responses:
        '200':
          description: API scopes successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_api_scopes_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/apis/{api_id}/scopes/{scope_id}:
    servers: []
    get:
      tags:
      - APIs
      operationId: getAPIScope
      summary: Get API scope
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      - name: scope_id
        in: path
        description: Scope ID
        required: true
        schema:
          type: string
          example: api_scope_019391daf58d87d8a7213419c016ac95
      description: 'Retrieve API scope by API ID.


        read:api_scopes'
      responses:
        '200':
          description: API scope successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_scope_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    patch:
      tags:
      - APIs
      operationId: updateAPIScope
      summary: Update API scope
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      - name: scope_id
        in: path
        description: Scope ID
        required: true
        schema:
          type: string
          example: api_scope_019391daf58d87d8a7213419c016ac95
      description: 'Update an API scope.


        update:api_scopes'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: Description of the api scope purpose.
                  example: Scope for reading logs.
      responses:
        '200':
          description: API scope successfully updated
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - APIs
      operationId: deleteAPIScope
      summary: Delete API scope
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      - name: scope_id
        in: path
        description: Scope ID
        required: true
        schema:
          type: string
          example: api_scope_019391daf58d87d8a7213419c016ac95
      description: 'Delete an API scope you previously created.


        delete:apis_scopes'
      responses:
        '200':
          description: API scope successfully deleted.
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/apis/{api_id}/applications:
    servers: []
    parameters:
    - $ref: '#/components/parameters/api_id'
    patch:
      tags:
      - APIs
      operationId: updateAPIApplications
      summary: Authorize API applications
      description: 'Authorize applications to be allowed to request access tokens for an API


        update:apis'
      requestBody:
        description: The applications you want to authorize.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - applications
              properties:
                applications:
                  type: array
                  items:
                    type: object
                    required:
                    - id
                    properties:
                      id:
                        description: The application's Client ID.
                        type: string
                        example: d2db282d6214242b3b145c123f0c123
                      operation:
                        description: Optional operation, set to 'delete' to revoke authorization for the application. If not set, the application will be authorized.
                        type: string
                        example: delete
      responses:
        '200':
          description: Authorized applications updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorize_app_api_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/apis/{api_id}/applications/{application_id}/scopes/{scope_id}:
    servers: []
    post:
      tags:
      - APIs
      operationId: addAPIApplicationScope
      summary: Add scope to API application
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      - name: application_id
        in: path
        description: Application ID
        required: true
        schema:
          type: string
          example: 7643b487c97545aab79257fd13a1085a
      - name: scope_id
        in: path
        description: Scope ID
        required: true
        schema:
          type: string
          example: api_scope_019391daf58d87d8a7213419c016ac95
      description: 'Add a scope to an API application.


        create:api_application_scopes'
      responses:
        '200':
          description: API scope successfully added to API application
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - APIs
      operationId: deleteAPIApplicationScope
      summary: Delete API application scope
      parameters:
      - name: api_id
        in: path
        description: API ID
        required: true
        schema:
          type: string
          example: 838f208d006a482dbd8cdb79a9889f68
      - name: application_id
        in: path
        description: Application ID
        required: true
        schema:
          type: string
          example: 7643b487c97545aab79257fd13a1085a
      - name: scope_id
        in: path
        description: Scope ID
        required: true
        schema:
          type: string
          example: api_scope_019391daf58d87d8a7213419c016ac95
      description: 'Delete an API application scope you previously created.


        delete:apis_application_scopes'
      responses:
        '200':
          description: API scope successfully deleted.
        '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'
    get_api_scopes_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: success_response
        scopes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique ID of the API scope.
                example: api_scope_01939128c3d7193ae87c4755213c07c6
              key:
                type: string
                description: The scope's reference key.
                example: read:logs
              description:
                type: string
                description: Explanation of the scope purpose.
                example: Read logs scope
    get_api_scope_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: success_response
        scope:
          type: object
          properties:
            id:
              type: string
              description: Unique ID of the API scope.
              example: api_scope_01939128c3d7193ae87c4755213c07c6
            key:
              type: string
              description: The scope's reference key.
              example: read:logs
            description:
              type: string
              description: Explanation of the scope purpose.
              example: Read logs scope
    delete_api_response:
      type: object
      properties:
        message:
          type: string
          example: API successfully deleted
        code:
          type: string
          example: API_DELETED
    authorize_app_api_response:
      type: object
      properties:
        message:
          type: string
          example: API applications updated
        code:
          type: string
          example: API_APPLICATIONS_UPDATED
        applications_disconnected:
          type: array
          items:
            type: string
        applications_connected:
          type: array
          items:
            type: string
            example: d2db282d6214242b3b145c123f0c123
    create_apis_response:
      type: object
      properties:
        message:
          type: string
          description: A Kinde generated message.
          example: Success
        code:
          type: string
          description: A Kinde generated status code.
          example: OK
        api:
          type: object
          properties:
            id:
              description: The unique ID for the API.
              type: string
              example: 7ccd126599aa422a771abcb341596881
    get_apis_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        next_token:
          type: string
          description: Pagination token.
          example: Njo5Om1hvWVfYXNj
        apis:
          type: array
          items:
            type: object
            properties:
              id:
                description: The unique ID for the API.
                type: string
                example: 7ccd126599aa422a771abcb341596881
              name:
                type: string
                description: The API's name.
                example: Example API
              audience:
                type: string
                description: A unique identifier for the API - commonly the URL. This value will be used as the `audience` parameter in authorization claims.
                example: https://api.example.com
              is_management_api:
                type: boolean
                description: Whether or not it is the Kinde management API.
                example: false
              scopes:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: api_scope_01939128c3d7193ae87c4755213c07c6
                    key:
                      type: string
                      example: create:apis
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
    get_api_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: success_response
        api:
          type: object
          properties:
            id:
              type: string
              description: Unique ID of the API.
              example: 7ccd126599aa422a771abcb341596881
            name:
              type: string
              description: The API's name.
              example: Example API
            audience:
              type: string
              description: A unique identifier for the API - commonly the URL. This value will be used as the `audience` parameter in authorization claims.
              example: https://api.example.com
            is_management_api:
              type: boolean
              description: Whether or not it is the Kinde management API.
              example: false
            scopes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the scope.
                    example: api_scope_01939222ef24200668b9f5829af001ce
                  key:
                    type: string
                    description: The reference key for the scope.
                    example: read:logs
            applications:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: The Client ID of the application.
                    example: 3b0b5c6c8fcc464fab397f4969b5f482
                  name:
                    type: string
                    description: The application's name.
                    example: My M2M app
                  type:
                    type: string
                    description: The application's type.
                    enum:
                    - Machine to machine (M2M)
                    - Back-end web
                    - Front-end and mobile
                    - Device and IoT
                    example: Machine to machine (M2M)
                  is_active:
                    type:
                    - boolean
                    - 'null'
                    description: Whether or not the application is authorized to access the API
                    example: true
    create_api_scopes_response:
      type: object
      properties:
        message:
          type: string
          description: A Kinde generated message.
          example: Success
        code:
          type: string
          description: A Kinde generated status code.
          example: OK
        scope:
          type: object
          properties:
            id:
              description: The unique ID for the API scope.
              type: string
              example: api_scope_0193ab57965aef77b2b687d0ef673713
  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'
  parameters:
    api_id:
      in: path
      name: api_id
      description: The API's ID.
      required: true
      schema:
        type: string
        example: 7ccd126599aa422a771abcb341596881
  securitySchemes:
    kindeBearerAuth:
      description: 'Requires an access token obtained using the client_credentials flow.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT