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

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[] · min: 1 · max: 1OptionalDeprecated

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

user_identity_idstringOptional

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 (or at which the existing client session expires), in ISO 8601 format.

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: 160

{
  "user_identifier_key": "text",
  "connect_webview_ids": [
    "text"
  ],
  "connected_account_ids": [
    "text"
  ],
  "user_identity_id": "text",
  "expires_at": "2025-06-17T04:45:24.699Z"
}

{
  "client_session": {
    "client_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-06-17T04:45:24.699Z",
    "expires_at": "2025-06-17T04:45:24.699Z",
    "token": "text",
    "user_identifier_key": "text",
    "device_count": 1,
    "customer_id": "123e4567-e89b-12d3-a456-426614174000",
    "connected_account_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "connect_webview_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "user_identity_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'
}