Get or Create a Client Session

Get a client session with specific characteristics or create it if it does not yet exist

Gets a client session with specific characteristics or create a new client session with these characteristics if it does not yet exist.

/client_sessions/get_or_create

post

Authorizations

publishable_keyapi_keypat_with_workspaceconsole_session_with_workspace

Body

user_identifier_keystring · min: 1optional

connect_webview_idsstring[]optional

connected_account_idsstring[]optional

user_identity_idsstring[]optional

expires_atstring · date-timeoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://connect.getseam.com/client_sessions/get_or_create' \
  --header 'seam-publishable-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_identifier_key": "text",
    "connect_webview_ids": [
      "text"
    ],
    "connected_account_ids": [
      "text"
    ],
    "user_identity_ids": [
      "text"
    ],
    "expires_at": "2025-04-03T04:26:49.709Z"
  }'

200

400

401

200

{
  "client_session": {
    "client_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-04-03T04:26:49.709Z",
    "expires_at": "2025-04-03T04:26:49.709Z",
    "token": "text",
    "user_identifier_key": "text",
    "device_count": 1,
    "connected_account_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "connect_webview_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "user_identity_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  },
  "ok": true
}

OK

Request

Specify any combination of desired client session characteristics by including the corresponding parameters in the request body.

Request Body Parameters

Parameter	Type	Description
user_identifier_key	String Optional	Your own internal user ID for the user to associate with the client session (or that is already associated with the existing client session)
connect_webview_ids	Array of strings Optional	Array of IDs of the Connect Webviews to associate with the client session (or that are already associated with the existing client session)
connected_account_ids	Array of strings Optional	Array of IDs of the connected accounts to associate with the client session (or that are already associated with the existing client session)
user_identity_ids	Array of strings Optional	Array of IDs of the user identities to associate with the client session (or that are already associated with the existing client session)
expires_at	String Optional	Date and time at which the client session should expire (or at which the existing client session expires)

Sample Request

JavaScript

await seam.clientSessions.getOrCreate({
  user_identifier_key: "internal-user-id-1",
  connected_account_ids: [
    "3ea0b67f-649f-4131-bfe3-f2035e77a3f9",
    "6e1cad57-b244-40ca-b4f3-30a46c8000d4",
  ]
})

Response

Returns a client_session containing the following properties:

Property	Description
token	Client session token associated with the client session
workspace_id	ID of the workspace that contains the client session
user_identifier_key	Your own internal user ID for the user
client_session_id	ID of the client session
created_at	Date and time at which the client session was created

This response also includes a Boolean ok status indicator.

Sample Response

JSON

{
  token: 'seam_cst12GGG4LUp_AoHvcSx39aY4AoHQ7GdMDRTH',
  workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
  user_identifier_key: 'internal user ID 1',
  client_session_id: '911b4a3f-e566-44a9-a8ac-267d9e586754',
  created_at: '2023-12-26T05:11:55.048Z'
}