> ## 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 > Creates a short-lived connect session and returns the token and auth link that open the account-linking flow for one end-user. ## 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 description: >- Creates a short-lived connect session and returns the token and auth link that open the account-linking flow for one end-user. 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: >- Could not create a connect session as the provider is not enabled on this project 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. The session binds to the project default connector profile when the caller may use it, otherwise to another connector profile for the provider that the caller may use; if none is usable the request is refused. Omit to show the full provider selection screen. To target a specific connector profile, use connector_profile_id instead. nullable: true provider_version: type: string deprecated: true description: >- Deprecated. When supplied, provider_version restricts binding to connector profiles of that version, so a version with no usable profile causes session creation to fail. Omit it to bind the default connector profile (or another the caller may use). To target a specific connector profile, use connector_profile_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 (this is an alias for it). 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 binds to the project default connector profile when the caller may use it, otherwise to another connector profile for the provider that the caller may use. 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 binds to the project default connector profile when the caller may use it, otherwise to another connector profile for the provider that the caller may use. 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. type: object 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 type: object 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.