Skip to main content
POST
/
connect_sessions
Create Connect Session
curl --request POST \
  --url https://api.stackone.com/connect_sessions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "origin_owner_id": "<string>",
  "origin_owner_name": "<string>",
  "categories": [
    "ats",
    "hris",
    "hrisLegacy",
    "crm",
    "iam",
    "marketing",
    "lms",
    "stackOne",
    "documents",
    "ticketing",
    "screening",
    "messaging",
    "accounting",
    "scheduling"
  ],
  "provider": "<string>",
  "provider_version": "<string>",
  "origin_username": "<string>",
  "account_id": "<string>",
  "expires_in": 1800,
  "metadata": {},
  "multiple": false,
  "label": "<string>",
  "type": [
    "PRODUCTION",
    "TEST"
  ],
  "integration_id": "<string>"
}
'
{
  "id": 123,
  "organization_id": "<string>",
  "project_id": "<string>",
  "origin_owner_id": "<string>",
  "origin_owner_name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "token": "<string>",
  "auth_link_url": "<string>",
  "categories": [
    "ats",
    "hris",
    "hrisLegacy",
    "crm",
    "iam",
    "marketing",
    "lms",
    "stackOne",
    "documents",
    "ticketing",
    "screening",
    "messaging",
    "accounting",
    "scheduling"
  ],
  "provider": "<string>",
  "origin_username": "<string>",
  "account_id": "<string>",
  "label": "<string>",
  "metadata": {},
  "external_trigger_token": "f0bc3d88-2178-5423-8c81-b81d6c9da824",
  "type": [
    "PRODUCTION",
    "TEST"
  ],
  "integration_id": "<string>",
  "latest_connection_attempt": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "status": "pending",
    "account_secure_id": "<string>",
    "oauth_error_code": "<string>",
    "oauth_error_description": "<string>"
  }
}

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.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
​
origin_owner_id
string
required

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
string
required

A human-readable name for the organization. Stored against the linked account in StackOne for identification purposes.

​
categories
enum<string>[] | null

The categories of the provider to connect to

Available options:
ats,
hris,
hris-legacy,
crm,
iam,
marketing,
lms,
stackone,
documents,
ticketing,
screening,
messaging,
accounting,
scheduling,
null
Example:
[
  "ats",
  "hris",
  "hrisLegacy",
  "crm",
  "iam",
  "marketing",
  "lms",
  "stackOne",
  "documents",
  "ticketing",
  "screening",
  "messaging",
  "accounting",
  "scheduling"
]
​
provider
string | null

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.

​
provider_version
string | null
deprecated

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.

​
origin_username
string | null

The origin username

​
account_id
string | null

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.

​
expires_in
number | null
default:1800

How long the session should be valid for in seconds

​
metadata
object

The metadata for the connection

​
multiple
boolean | null
default:false

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.

​
label
string | null

The label to be applied to the account associated with this connect session.

​
type
enum<string> | null
default:production

The connect session account type

Available options:
production,
test,
null
Example:
["PRODUCTION", "TEST"]
​
integration_id
string | null

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.

Response

The details of the connect session created with token and auth link

​
id
number
required
​
organization_id
string
required
​
project_id
string
required
​
origin_owner_id
string
required
​
origin_owner_name
string
required
​
created_at
string<date-time>
required
​
token
string
required
​
auth_link_url
string
required
​
categories
enum<string>[] | null
Available options:
ats,
hris,
hris-legacy,
crm,
iam,
marketing,
lms,
stackone,
documents,
ticketing,
screening,
messaging,
accounting,
scheduling,
null
Example:
[
  "ats",
  "hris",
  "hrisLegacy",
  "crm",
  "iam",
  "marketing",
  "lms",
  "stackOne",
  "documents",
  "ticketing",
  "screening",
  "messaging",
  "accounting",
  "scheduling"
]
​
provider
string | null
​
origin_username
string | null
​
account_id
string | null
​
label
string | null
​
metadata
object

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)

​
external_trigger_token
string | null

External trigger token to be used to trigger actions on the account

Example:

"f0bc3d88-2178-5423-8c81-b81d6c9da824"

​
type
enum<string> | null

The connect session account type

Available options:
production,
test,
unmapped_value,
null
Example:
["PRODUCTION", "TEST"]
​
integration_id
string | null

The integration ID (UUID) associated with this connect session

​
latest_connection_attempt
object

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.