> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Connect Session



## OpenAPI

````yaml post /connect_sessions
openapi: 3.1.0
info:
  title: StackOne
  description: The documentation for the StackOne API
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.stackone.com
security: []
tags:
  - name: Accounts
    description: View and manage linked accounts.
  - name: Actions
    description: Retrieve Actions metadata and definitions.
  - name: AI
    description: AI-powered features.
  - name: Auth Configs
    description: View and manage connector auth configurations for the project.
  - name: Connect Sessions
    description: >-
      Generate connection session tokens or auth URLs to allow your customers to
      connect their accounts.
  - name: Connector Profiles
    description: View and manage connector profiles for the project.
  - name: Connectors
    description: Retrieve metadata for connectors.
  - name: Logs
    description: API request logs and analytics.
  - name: MCP
    description: Model Context Protocol endpoint.
  - name: Proxy
    description: Routing API requests through StackOne directly to the underlying provider.
  - name: Request Logs
    description: API requests and response logs.
  - name: Webhooks
    description: Configure and manage webhooks.
paths:
  /connect_sessions:
    post:
      tags:
        - Connect Sessions
      summary: Create Connect Session
      operationId: stackone_create_connect_session
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectSessionCreate'
      responses:
        '201':
          description: The details of the connect session created with token and auth link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectSessionTokenAuthLink'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '408':
          description: The request has timed out.
          headers:
            Retry-After:
              description: A time in seconds after which the request can be retried.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTimedOutResponse'
        '409':
          description: Conflict with current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
        '500':
          description: Server error while executing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
        '501':
          description: This functionality is not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
        '502':
          description: Bad gateway error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayResponse'
      security:
        - basic: []
components:
  schemas:
    ConnectSessionCreate:
      type: object
      properties:
        categories:
          type: array
          description: The categories of the provider to connect to
          example:
            - ats
            - hris
            - hrisLegacy
            - crm
            - iam
            - marketing
            - lms
            - stackOne
            - documents
            - ticketing
            - screening
            - messaging
            - accounting
            - scheduling
          x-speakeasy-unknown-values: allow
          nullable: true
          items:
            type: string
            enum:
              - ats
              - hris
              - hris-legacy
              - crm
              - iam
              - marketing
              - lms
              - stackone
              - documents
              - ticketing
              - screening
              - messaging
              - accounting
              - scheduling
              - null
        provider:
          type: string
          description: >-
            The provider key to connect to (e.g. "salesforce", "bamboohr"). When
            provided, the hub opens directly at the credential entry step for
            this provider using the project default auth config. Omit to show
            the full provider selection screen. To use a non-default auth
            config, use integration_id instead.
          nullable: true
        provider_version:
          type: string
          deprecated: true
          description: >-
            Deprecated. provider_version no longer determines which connector
            version is used for the session and can cause session creation to
            fail. Omit this field — passing provider alone will create a session
            using the default auth config. To target a specific auth config, use
            integration_id.
          nullable: true
        origin_owner_id:
          type: string
          description: >-
            The unique identifier for the organization in your system (e.g. your
            customer's org ID). Combined with origin_owner_name and provider,
            this determines whether a new linked account is created or an
            existing one is updated.
        origin_owner_name:
          type: string
          description: >-
            A human-readable name for the organization. Stored against the
            linked account in StackOne for identification purposes.
        origin_username:
          type: string
          description: The origin username
          nullable: true
        account_id:
          type: string
          description: >-
            The unique identifier for the account associated with this connect
            session. When this field is present, the hub will launch in edit
            mode using the retrieved token.
          nullable: true
        expires_in:
          type: number
          description: How long the session should be valid for in seconds
          default: 1800
          nullable: true
        metadata:
          type: object
          description: The metadata for the connection
          nullable: true
        multiple:
          type: boolean
          description: >-
            If set, this connect session will allow creation of multiple
            accounts with the same origin owner id and provider. Has no effect
            if account_id is set.
          default: false
          nullable: true
        label:
          type: string
          description: >-
            The label to be applied to the account associated with this connect
            session.
          nullable: true
        type:
          type: string
          description: The connect session account type
          enum:
            - production
            - test
            - null
          example:
            - PRODUCTION
            - TEST
          default: production
          x-speakeasy-unknown-values: allow
          nullable: true
        integration_id:
          type: string
          description: >-
            Deprecated: use `connector_profile_id` instead. The ID of the auth
            config to use for this connect session. Use this to route to a
            non-default auth config — for example when you have multiple configs
            for the same provider, or when migrating end users to a new
            connector major version. Retrieve the ID from GET /auth_configs.
            When omitted, the session uses the project default auth config for
            the given provider.
          deprecated: true
          nullable: true
        connector_profile_id:
          type: string
          description: >-
            The ID of the connector profile to use for this connect session. Use
            this to route to a non-default connector profile — for example when
            you have multiple profiles for the same provider, or when migrating
            end users to a new connector major version. Retrieve the ID from GET
            /connector_profiles. When omitted, the session uses the project
            default connector profile for the given provider.
          nullable: true
      required:
        - origin_owner_id
        - origin_owner_name
    ConnectSessionTokenAuthLink:
      type: object
      properties:
        id:
          type: number
        organization_id:
          type: string
        project_id:
          type: string
        categories:
          type: array
          example:
            - ats
            - hris
            - hrisLegacy
            - crm
            - iam
            - marketing
            - lms
            - stackOne
            - documents
            - ticketing
            - screening
            - messaging
            - accounting
            - scheduling
          x-speakeasy-unknown-values: allow
          nullable: true
          items:
            type: string
            enum:
              - ats
              - hris
              - hris-legacy
              - crm
              - iam
              - marketing
              - lms
              - stackone
              - documents
              - ticketing
              - screening
              - messaging
              - accounting
              - scheduling
              - null
        provider:
          type: string
          nullable: true
        origin_owner_id:
          type: string
        origin_owner_name:
          type: string
        origin_username:
          type: string
          nullable: true
        account_id:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          description: >-
            Arbitrary set of key and values defined during the session token
            creation. This can be used to tag an account (eg. based on their
            pricing plan)
          nullable: true
        external_trigger_token:
          type: string
          description: External trigger token to be used to trigger actions on the account
          example: f0bc3d88-2178-5423-8c81-b81d6c9da824
          nullable: true
        type:
          type: string
          description: The connect session account type
          enum:
            - production
            - test
            - unmapped_value
            - null
          example:
            - PRODUCTION
            - TEST
          x-speakeasy-unknown-values: allow
          nullable: true
        integration_id:
          type: string
          description: >-
            Deprecated: use `connector_profile_id` instead. The integration ID
            (UUID) associated with this connect session.
          deprecated: true
          nullable: true
        connector_profile_id:
          type: string
          description: The connector profile ID associated with this connect session
          nullable: true
        latest_connection_attempt:
          nullable: true
          description: >-
            The most recent connection attempt initiated against this session,
            if any. Use this to poll for OAuth completion: when status is
            "authenticated", the resulting account is at account_secure_id.
          allOf:
            - $ref: '#/components/schemas/ConnectSessionLatestAttempt'
        token:
          type: string
        auth_link_url:
          type: string
      required:
        - id
        - organization_id
        - project_id
        - origin_owner_id
        - origin_owner_name
        - created_at
        - token
        - auth_link_url
    BadRequestResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Error message
          example: Bad Request
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
        data:
          description: Error details
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UnifiedError'
        provider_errors:
          description: List of provider-specific errors
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/ProviderError'
      required:
        - statusCode
        - message
        - timestamp
    UnauthorizedResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 401
        message:
          type: string
          description: Error message
          example: Unauthorized
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    ForbiddenResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 403
        message:
          type: string
          description: Error message
          example: Forbidden resource
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    NotFoundResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 404
        message:
          type: string
          description: Error message
          example: Not Found
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    RequestTimedOutResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 408
        message:
          type: string
          description: Error message
          example: Request timed out
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    ConflictResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 409
        message:
          type: string
          description: Error message
          example: Conflict
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    UnprocessableEntityResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 422
        message:
          type: string
          description: Error message
          example: Unprocessable Entity
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    TooManyRequestsResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 429
        message:
          type: string
          description: Error message
          example: Too many requests
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    InternalServerErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 500
        message:
          type: string
          description: Error message
          example: Internal server error
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    NotImplementedResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 501
        message:
          type: string
          description: Error message
          example: Not Implemented
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    BadGatewayResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 502
        message:
          type: string
          description: Error message
          example: Bad Gateway
        timestamp:
          type: string
          description: Timestamp when the error occurred
          example: '2023-05-30T00:00:00.000Z'
          format: date-time
      required:
        - statusCode
        - message
        - timestamp
    ConnectSessionLatestAttempt:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - authenticated
            - error
            - cancelled
            - null
          example: pending
          x-speakeasy-unknown-values: allow
          nullable: true
        account_secure_id:
          type: string
          nullable: true
          description: >-
            The secure id of the account created/updated by this attempt.
            Populated only after a successful authentication.
        oauth_error_code:
          type: string
          nullable: true
        oauth_error_description:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - created_at
        - updated_at
    UnifiedError:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 400
          nullable: true
        message:
          type: string
          description: Error message
          example: Bad Request
          nullable: true
        headers:
          type: object
          description: Response headers
          example:
            content-type: application/json
            x-request-id: 5678c28b211dace4e0a0f9171e6b88c5
          nullable: true
    ProviderError:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code of the provider error
          example: 400
          nullable: true
        url:
          type: string
          description: URL that caused the error
          example: https://api.provider.com/v1/resource
          nullable: true
        raw:
          type: object
          description: Raw error response from the provider
          example:
            message: Invalid input parameters
          nullable: true
        headers:
          type: object
          description: Response headers
          example:
            content-type: application/json
            x-request-id: 5678c28b211dace4e0a0f9171e6b88c5
          nullable: true
  securitySchemes:
    basic:
      type: http
      scheme: basic

````