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

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

Authorizations

publishable_keyapi_keypat_with_workspaceconsole_session_with_workspace

Body

application/json

user_identifier_keystring · min: 1Optional

Your user ID for the user that you want to associate with the client session (or that is already associated with the existing client session).

connect_webview_idsstring[]Optional

IDs of the Connect Webviews that you want to associate with the client session (or that are already associated with the existing client session).

connected_account_idsstring[]Optional

IDs of the connected accounts that you want to associate with the client session (or that are already associated with the existing client session).

user_identity_idsstring · uuid[] · min: 1 · max: 1OptionalDeprecated

IDs of the user identities that you want to associate with the client session.

user_identity_idstring · uuidOptional

ID of the user identity that you want to associate with the client session (or that are already associated with the existing client session).

expires_atstring · date-timeOptional

Date and time at which the client session should expire in ISO 8601 format. If the client session already exists, this will update the expiration before returning it.

Responses

200

OK

application/json

400

Bad Request

401

Unauthorized

post

HTTPcURLJavaScriptPython

POST /client_sessions/get_or_create HTTP/1.1
Host: connect.getseam.com
seam-publishable-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 192

{
  "user_identifier_key": "text",
  "connect_webview_ids": [
    "text"
  ],
  "connected_account_ids": [
    "text"
  ],
  "user_identity_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_at": "2025-10-17T10:23:49.087Z"
}

{
  "client_session": {
    "client_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-10-17T10:23:49.087Z",
    "expires_at": "2025-10-17T10:23:49.087Z",
    "token": "text",
    "user_identifier_key": "text",
    "device_count": 1,
    "customer_key": "text",
    "connected_account_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "connect_webview_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "user_identity_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "ok": true
}

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