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

POSThttps://connect.getseam.com/client_sessions/get_or_create

Authorization

publishable_keyapi_keypat_with_workspaceconsole_session_with_workspace

Body

application/json

user_identifier_keystring

connect_webview_idsarray of string

connected_account_idsarray of string

user_identity_idsarray of string

expires_atstring (date-time)

Response

200400401

OK

Body

application/json

client_session*client_session (object)

ok*boolean

Request

JavaScriptCurlPython

const response = await fetch('https://connect.getseam.com/client_sessions/get_or_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "client_session": {
    "client_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-01-20T19:04:38.628Z",
    "expires_at": "2025-01-20T19:04:38.628Z",
    "token": "text",
    "user_identifier_key": "text",
    "device_count": 0,
    "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": false
}

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'
}