WorkOS user-management.data-providers API

openapi: 3.1.1
info:
  title: WorkOS admin-portal user-management.data-providers API
  description: WorkOS REST API
  version: '1.0'
  contact:
    name: WorkOS
    url: https://workos.com
    email: support@workos.com
  license:
    name: MIT
    url: https://opensource.org/license/MIT
servers:
- url: https://api.workos.com
  description: Production
- url: https://api.workos-test.com
  description: Staging
security:
- bearer: []
tags:
- name: user-management.data-providers
  description: Manage data providers.
  x-displayName: Data Providers
paths:
  /user_management/users/{user_id}/connected_accounts/{slug}:
    get:
      description: Retrieves a user's [connected account](/reference/pipes/connected-account) for a specific provider.
      operationId: DataIntegrationsUserManagementController_getUserDataInstallation
      parameters:
      - name: user_id
        required: true
        in: path
        description: A [User](/reference/authkit/user) identifier.
        schema:
          example: user_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      - name: slug
        required: true
        in: path
        description: The slug identifier of the provider (e.g., `github`, `slack`, `notion`).
        schema:
          example: github
          type: string
      - name: organization_id
        required: false
        in: query
        description: An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization.
        schema:
          example: org_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      responses:
        '200':
          description: The connected account was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectedAccount'
        '401':
          description: The request is missing a valid API key.
        '404':
          description: The user, organization, or connected account was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Get a Connected Account
      tags:
      - user-management.data-providers
    delete:
      description: Disconnects WorkOS's account for the user, including removing any stored access and refresh tokens. The user will need to reauthorize if they want to reconnect. This does not revoke access on the provider side.
      operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation
      parameters:
      - name: user_id
        required: true
        in: path
        description: A [User](/reference/authkit/user) identifier.
        schema:
          example: user_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      - name: slug
        required: true
        in: path
        description: The slug identifier of the provider (e.g., `github`, `slack`, `notion`).
        schema:
          example: github
          type: string
      - name: organization_id
        required: false
        in: query
        description: An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization.
        schema:
          example: org_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      responses:
        '204':
          description: The connected account was deleted successfully.
        '401':
          description: The request is missing a valid API key.
        '404':
          description: The user, organization, or connected account was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Delete a Connected Account
      tags:
      - user-management.data-providers
  /user_management/users/{user_id}/data_providers:
    get:
      description: Retrieves a list of available providers and the user's connection status for each. Returns all providers configured for your environment, along with the user's [connected account](/reference/pipes/connected-account) information where applicable.
      operationId: DataIntegrationsUserManagementController_getUserDataIntegrations
      parameters:
      - name: user_id
        required: true
        in: path
        description: A [User](/reference/authkit/user) identifier to list providers and connected accounts for.
        schema:
          example: user_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      - name: organization_id
        required: false
        in: query
        description: An [Organization](/reference/organization) identifier. Optional parameter to filter connections for a specific organization.
        schema:
          example: org_01EHZNVPK3SFK441A1RGBFSHRT
          type: string
      responses:
        '200':
          description: The list of data providers was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataIntegrationsListResponse'
        '401':
          description: The request is missing a valid API key.
        '404':
          description: The user or organization was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: List Providers
      tags:
      - user-management.data-providers
components:
  schemas:
    DataIntegrationsListResponse:
      type: object
      properties:
        object:
          type: string
          description: Indicates this is a list response.
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              object:
                type: string
                description: Distinguishes the data provider object.
                const: data_provider
              id:
                type: string
                description: The unique identifier of the provider.
                example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT
              name:
                type: string
                description: The display name of the provider (e.g., "GitHub", "Slack").
                example: GitHub
              description:
                type:
                - string
                - 'null'
                description: A description of the provider explaining how it will be used, if configured.
                example: Connect your GitHub account to access repositories.
              slug:
                type: string
                description: The slug identifier used in API calls (e.g., `github`, `slack`, `notion`).
                example: github
              integration_type:
                type: string
                description: The type of integration (e.g., `github`, `slack`).
                example: github
              credentials_type:
                type: string
                description: The type of credentials used by the provider (e.g., `oauth2`).
                example: oauth2
              scopes:
                description: The OAuth scopes configured for this provider, or `null` if none are configured.
                example:
                - repo
                - user:email
                oneOf:
                - type: array
                  items:
                    type: string
                - type: 'null'
              ownership:
                type: string
                enum:
                - userland_user
                - organization
                description: Whether the provider is owned by a user or organization.
              created_at:
                type: string
                description: The timestamp when the provider was created.
                example: '2024-01-15T10:30:00.000Z'
              updated_at:
                type: string
                description: The timestamp when the provider was last updated.
                example: '2024-01-15T10:30:00.000Z'
              integrationType:
                type: string
                deprecated: true
                description: Use integration_type instead.
              credentialsType:
                type: string
                deprecated: true
                description: Use credentials_type instead.
              createdAt:
                type: string
                deprecated: true
                description: Use created_at instead.
              updatedAt:
                type: string
                deprecated: true
                description: Use updated_at instead.
              connected_account:
                description: The user's [connected account](/reference/pipes/connected-account) for this provider, or `null` if the user has not connected.
                oneOf:
                - type: object
                  properties:
                    object:
                      type: string
                      description: Distinguishes the connected account object.
                      const: connected_account
                    id:
                      type: string
                      description: The unique identifier of the connected account.
                      example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT
                    user_id:
                      type:
                      - string
                      - 'null'
                      description: The [User](/reference/authkit/user) identifier associated with this connection.
                      example: user_01EHZNVPK3SFK441A1RGBFSHRT
                    organization_id:
                      type:
                      - string
                      - 'null'
                      description: The [Organization](/reference/organization) identifier associated with this connection, or `null` if not scoped to an organization.
                      example: null
                    scopes:
                      type: array
                      items:
                        type: string
                      description: The OAuth scopes granted for this connection.
                      example:
                      - repo
                      - user:email
                    state:
                      type: string
                      enum:
                      - connected
                      - needs_reauthorization
                      - disconnected
                      description: 'The state of the connected account:

                        - `connected`: The connection is active and tokens are valid.

                        - `needs_reauthorization`: The user needs to reauthorize the connection, typically because required scopes have changed.

                        - `disconnected`: The connection has been disconnected.'
                      example: connected
                    created_at:
                      type: string
                      description: The timestamp when the connection was created.
                      example: '2024-01-16T14:20:00.000Z'
                    updated_at:
                      type: string
                      description: The timestamp when the connection was last updated.
                      example: '2024-01-16T14:20:00.000Z'
                    userlandUserId:
                      type:
                      - string
                      - 'null'
                      deprecated: true
                      description: Use `user_id` instead.
                    organizationId:
                      type:
                      - string
                      - 'null'
                      deprecated: true
                      description: Use `organization_id` instead.
                    createdAt:
                      type: string
                      deprecated: true
                      description: Use `created_at` instead.
                    updatedAt:
                      type: string
                      deprecated: true
                      description: Use `updated_at` instead.
                  required:
                  - object
                  - id
                  - user_id
                  - organization_id
                  - scopes
                  - state
                  - created_at
                  - updated_at
                  - userlandUserId
                  - organizationId
                  - createdAt
                  - updatedAt
                - type: 'null'
            required:
            - object
            - id
            - name
            - description
            - slug
            - integration_type
            - credentials_type
            - scopes
            - ownership
            - created_at
            - updated_at
            - integrationType
            - credentialsType
            - createdAt
            - updatedAt
            - connected_account
          description: A list of [providers](/reference/pipes/provider), each including a [`connected_account`](/reference/pipes/connected-account) field with the user's connection status.
      required:
      - object
      - data
    ConnectedAccount:
      type: object
      properties:
        object:
          type: string
          description: Distinguishes the connected account object.
          const: connected_account
        id:
          type: string
          description: The unique identifier of the connected account.
          example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT
        user_id:
          type:
          - string
          - 'null'
          description: The [User](/reference/authkit/user) identifier associated with this connection.
          example: user_01EHZNVPK3SFK441A1RGBFSHRT
        organization_id:
          type:
          - string
          - 'null'
          description: The [Organization](/reference/organization) identifier associated with this connection, or `null` if not scoped to an organization.
          example: null
        scopes:
          type: array
          items:
            type: string
          description: The OAuth scopes granted for this connection.
          example:
          - repo
          - user:email
        state:
          type: string
          enum:
          - connected
          - needs_reauthorization
          - disconnected
          description: 'The state of the connected account:

            - `connected`: The connection is active and tokens are valid.

            - `needs_reauthorization`: The user needs to reauthorize the connection, typically because required scopes have changed.

            - `disconnected`: The connection has been disconnected.'
          example: connected
        created_at:
          type: string
          description: The timestamp when the connection was created.
          example: '2024-01-16T14:20:00.000Z'
        updated_at:
          type: string
          description: The timestamp when the connection was last updated.
          example: '2024-01-16T14:20:00.000Z'
      required:
      - object
      - id
      - user_id
      - organization_id
      - scopes
      - state
      - created_at
      - updated_at
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.'
    access_token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: An SSO access token returned from the Get a Profile and Token endpoint.