openapi: 3.0.3
info:
  title: Knock Providers API
  version: '1.0'
  description: OAuth provider endpoints supporting SlackKit, MS Teams Kit, and other inbound provider integrations — authorize,
    revoke, and inspect connections to chat and notification providers on behalf of users or tenants.
  contact:
    name: Knock
    url: https://knock.app
  license:
    name: Proprietary
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
paths:
  /v1/providers/slack/{channel_id}/channels:
    get:
      callbacks: {}
      description: List Slack channels for a Slack workspace.
      operationId: listChannelsForSlackProvider
      parameters:
      - description: The ID of the Knock Slack channel to get channels for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned
          by a previous request's response_metadata. Default value fetches the first "page" of the collection.
        in: query
        name: query_options.cursor
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The maximum number of channels to return. Defaults to 200.
        in: query
        name: query_options.limit
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      - description: Set to true to exclude archived channels from the list. Defaults to `true` when not explicitly provided.
        in: query
        name: query_options.exclude_archived
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Mix and match channel types by providing a comma-separated list of any combination of public_channel,
          private_channel, mpim, im. Defaults to `"public_channel,private_channel"`. If the user's Slack ID is unavailable,
          this option is ignored and only public channels are returned.
        in: query
        name: query_options.types
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Encoded team ID (T1234) to list channels in, required if org token is used.
        in: query
        name: query_options.team_id
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelsForSlackProviderResponse'
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                    x-struct: null
                    x-validate: null
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                    x-struct: null
                    x-validate: null
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                    x-struct: null
                    x-validate: null
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
                x-struct: null
                x-validate: null
          description: Forbidden
      summary: List channels
      tags:
      - Providers
      - Slack
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/auth_check:
    get:
      callbacks: {}
      description: Check if a connection to Microsoft Teams has been authorized for a given Microsoft Teams tenant object.
      operationId: msTeamsProviderAuthCheck
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to check.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsTeamsAuthCheckResponse'
          description: OK
      summary: Check auth
      tags:
      - Providers
      - Microsoft Teams
      x-ratelimit-tier: 2
  /v1/providers/slack/{channel_id}/auth_check:
    get:
      callbacks: {}
      description: Check if a Slack channel is authenticated.
      operationId: slackProviderAuthCheck
      parameters:
      - description: The ID of the Knock Slack channel to check.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackAuthCheckResponse'
          description: OK
      summary: Check auth
      tags:
      - Providers
      - Slack
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/channels:
    get:
      callbacks: {}
      description: List the Microsoft Teams channels within a team. By default, archived and private channels are excluded
        from the results.
      operationId: listChannelsForMsTeamsProvider
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to get channels for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Microsoft Teams team ID.
        in: query
        name: team_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to filter channels.'
        example: displayName eq 'General'
        in: query
        name: query_options.$filter
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to select specific properties.'
        example: id,displayName,description
        in: query
        name: query_options.$select
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelsForMsTeamsProviderResponse'
          description: OK
      summary: List channels
      tags:
      - Providers
      - Microsoft Teams
      x-ratelimit-tier: 2
  /v1/providers/slack/{channel_id}/revoke_access:
    put:
      callbacks: {}
      description: Revoke access for a Slack channel.
      operationId: slackProviderRevokeAccess
      parameters:
      - description: The ID of the Knock Slack channel to revoke access for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the access token object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: access_token_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A response indicating the operation was successful.
                example:
                  ok: ok
                properties:
                  ok:
                    description: OK response.
                    example: ok
                    type: string
                    x-struct: null
                    x-validate: null
                title: SuccessResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                    x-struct: null
                    x-validate: null
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                    x-struct: null
                    x-validate: null
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                    x-struct: null
                    x-validate: null
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
                x-struct: null
                x-validate: null
          description: Forbidden
      summary: Revoke access
      tags:
      - Providers
      - Slack
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/teams:
    get:
      callbacks: {}
      description: Get a list of teams belonging to the Microsoft Entra tenant. By default, archived and private channels
        are excluded from the results.
      operationId: listTeamsForMsTeamsProvider
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to get teams for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to filter teams.'
        example: displayName eq 'My Team'
        in: query
        name: query_options.$filter
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to select fields on a team.'
        example: id,displayName,description
        in: query
        name: query_options.$select
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to limit the number of teams returned.'
        example: 10
        in: query
        name: query_options.$top
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      - description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
          API to retrieve the next page of results.'
        in: query
        name: query_options.$skiptoken
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsForMsTeamsProviderResponse'
          description: OK
      summary: List teams
      tags:
      - Providers
      - Microsoft Teams
      x-ratelimit-tier: 2
  /v1/providers/ms-teams/{channel_id}/revoke_access:
    put:
      callbacks: {}
      description: Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.
      operationId: msTeamsProviderRevokeAccess
      parameters:
      - description: The ID of the Knock Microsoft Teams channel to revoke access for.
        in: path
        name: channel_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A JSON encoded string containing the Microsoft Teams tenant object reference.
        example: '{"collection":"projects","object_id":"project_123"}'
        in: query
        name: ms_teams_tenant_object
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A response indicating the operation was successful.
                example:
                  ok: ok
                properties:
                  ok:
                    description: OK response.
                    example: ok
                    type: string
                    x-struct: null
                    x-validate: null
                title: SuccessResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
        '403':
          content:
            application/json:
              schema:
                description: Authentication error response
                example:
                  code: authorization
                  message: Access token not set.
                  status: 403
                  type: authentication_error
                properties:
                  code:
                    description: The error code.
                    example: authorization
                    type: string
                    x-struct: null
                    x-validate: null
                  message:
                    description: The error message.
                    example: Access token not set.
                    type: string
                    x-struct: null
                    x-validate: null
                  status:
                    description: The HTTP status code.
                    example: 403
                    type: integer
                    x-struct: null
                    x-validate: null
                  type:
                    description: The error type.
                    example: authentication_error
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - code
                - message
                - status
                - type
                title: AuthenticationError
                type: object
                x-struct: null
                x-validate: null
          description: Forbidden
      summary: Revoke access
      tags:
      - Providers
      - Microsoft Teams
      x-ratelimit-tier: 2
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock API key as a Bearer token. Use a public key (pk_...) for client-side requests or a secret key (sk_...)
        for server-side.
  schemas:
    SlackAuthCheckResponse:
      description: The response from a Slack auth check request.
      example:
        connection:
          ok: true
      properties:
        connection:
          description: A Slack connection object.
          properties:
            ok:
              description: Whether the Slack connection is valid.
              nullable: false
              type: boolean
              x-struct: null
              x-validate: null
            reason:
              description: The reason for the Slack connection if it is not valid.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
          required:
          - ok
          type: object
          x-struct: null
          x-validate: null
      required:
      - connection
      title: SlackAuthCheckResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.SlackAuthCheckResponse
      x-validate: null
    ChannelsForSlackProviderResponse:
      description: The response from a Slack provider request, containing a list of channels.
      example:
        next_cursor: null
        slack_channels:
        - context_team_id: T01234567890
          id: C01234567890
          is_im: false
          is_private: false
          name: general
      properties:
        next_cursor:
          description: Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned
            by a previous request's response_metadata. Default value fetches the first "page" of the collection.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        slack_channels:
          description: List of Slack channels.
          items:
            description: A Slack channel.
            properties:
              context_team_id:
                description: The team ID that the Slack channel belongs to.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              id:
                description: A Slack channel ID from the Slack provider.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              is_im:
                description: Whether the Slack channel is an IM channel.
                nullable: false
                type: boolean
                x-struct: null
                x-validate: null
              is_private:
                description: Whether the Slack channel is private.
                nullable: false
                type: boolean
                x-struct: null
                x-validate: null
              name:
                description: Slack channel name.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
            required:
            - id
            - name
            - is_private
            - is_im
            - context_team_id
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      required:
      - slack_channels
      - next_cursor
      title: ChannelsForSlackProviderResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.ChannelsForSlackProviderResponse
      x-validate: null
    TeamsForMsTeamsProviderResponse:
      description: The response from a Microsoft Teams provider request, containing a list of teams.
      example:
        ms_teams_teams:
        - displayName: Engineering Team
          id: team-id-1
        skip_token: token-for-next-page
      properties:
        ms_teams_teams:
          description: List of Microsoft Teams teams.
          items:
            properties:
              description:
                description: Microsoft Teams team description.
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              displayName:
                description: Microsoft Teams team display name.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              id:
                description: Microsoft Teams team ID.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
            required:
            - id
            - displayName
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
        skip_token:
          description: '[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph
            API to retrieve the next page of results.'
          nullable: true
          type: string
          x-struct: null
          x-validate: null
      required:
      - ms_teams_teams
      - skip_token
      title: TeamsForMsTeamsProviderResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.TeamsForMsTeamsProviderResponse
      x-validate: null
    ChannelsForMsTeamsProviderResponse:
      description: The response from a Microsoft Teams provider request, containing a list of channels.
      example:
        ms_teams_channels:
        - displayName: General
          id: channel-id-1
      properties:
        ms_teams_channels:
          description: List of Microsoft Teams channels.
          items:
            properties:
              createdDateTime:
                description: Microsoft Teams channel created date and time.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              description:
                description: Microsoft Teams channel description.
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              displayName:
                description: Microsoft Teams channel name.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              id:
                description: Microsoft Teams channel ID.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
              isArchived:
                description: Whether the Microsoft Teams channel is archived.
                nullable: false
                type: boolean
                x-struct: null
                x-validate: null
              membershipType:
                description: Microsoft Teams channel membership type.
                nullable: false
                type: string
                x-struct: null
                x-validate: null
            required:
            - id
            - displayName
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      required:
      - ms_teams_channels
      title: ChannelsForMsTeamsProviderResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.ChannelsForMsTeamsProviderResponse
      x-validate: null
    MsTeamsAuthCheckResponse:
      description: The response from a Microsoft Teams auth check request.
      example:
        connection:
          ok: true
      properties:
        connection:
          description: A Microsoft Teams connection object.
          properties:
            ok:
              description: Whether the Microsoft Teams connection is valid.
              nullable: false
              type: boolean
              x-struct: null
              x-validate: null
            reason:
              description: The reason for the Microsoft Teams connection if it is not valid.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
          required:
          - ok
          type: object
          x-struct: null
          x-validate: null
      required:
      - connection
      title: MsTeamsAuthCheckResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsAuthCheckResponse
      x-validate: null