Identity & User Objects

YS Desk distinguishes between authenticated Workspace Team Members, external Visitors, and Visitor Sessions.

Identity Architecture

There are three primary identity contexts:

Identity	Purpose	Authentication Context
Team Member	Internal Workspace user such as Owner, Admin, or Agent	Authenticated dashboard identity
Visitor	External user interacting through Web Chat	Visitor identity associated with Workspace and Channel
Visitor Session	Time-bound Web Chat authentication context	HMAC-SHA256 signed session

A Visitor can be represented by a User record with role: GUEST.

User Object

A User represents a Workspace member or Visitor. For Team Members, relevant roles include Owner, Admin, and Agent.

Team Member Fields

Field	Type	Description
id	string	Unique User identifier.
uuid	string	Public external identifier where available.
name	string	Display name.
email	string	User email address.
picture	string	Profile image URL.
role	Role	Workspace role.
isOnline	boolean	Current online presence state.
workspaceId	string	Workspace association.
createdAt	ISO-8601 timestamp	Creation timestamp.
updatedAt	ISO-8601 timestamp	Last update timestamp.

Authentication-provider identifiers and authentication secrets are not part of the public Reference specification.

Guest Object

A Guest represents an external Web Chat Visitor.

Relevant identity fields include:

Field	Description
id	Guest User identifier.
uuid	Public external identifier where available.
name	Visitor display name.
email	Visitor email when provided.
role	GUEST.
channelId	Channel associated with the Visitor.
workspaceId	Workspace associated with the Visitor.
isOnline	Current Visitor presence state.

Visitor records are workspace- and channel-scoped.

Visitor Session Token

Visitor sessions use an HMAC-SHA256 signed session token.

Claims

{

  “workspaceId”: “<WORKSPACE_ID>”,

  “channelId”: “<CHANNEL_ID>”,

  “guestId”: “<GUEST_ID>”,

  “conversationId”: “<CONVERSATION_ID>”,

  “iat”: 0,

  “exp”: 0

}

Claim Definitions

Claim	Type	Description
workspaceId	string	Workspace to which the session belongs.
channelId	string	Channel through which the session was established.
guestId	string	Visitor identity when available.
conversationId	string	Associated Conversation when available.
iat	number	Token issuance timestamp.
exp	number	Token expiration timestamp.

The session token binds the Visitor session to the expected Workspace and Channel context. Invalid or expired sessions produce INVALID_VISITOR_SESSION.

User Presence & History

Presence and login-history data can contain device and connection context such as:

• IP address representation
• Browser
• Operating system
• Browser name
• Device type
• Session identifier
• Origin URL
• Login timestamp
• Geolocation information

Geolocation data may include:

city, region, country, latitude, longitude, timezone

Raw socket identifiers and session secrets are excluded from the public Reference specification.

Invitation Object

Invitations represent pending Workspace membership invitations.

Relevant fields include:

Field	Type	Description
id	string	Invitation identifier.
email	string	Invitee email address.
role	Role	Role assigned when the invitation is accepted.
permissions	object	Permission configuration associated with the invitation.
expiresAt	ISO-8601 timestamp	Invitation expiration time.
usedAt	ISO-8601 timestamp	Acceptance timestamp when used.
workspaceId	string	Target Workspace identifier.

The invitation token itself must not be published as a real credential. Use <INVITATION_TOKEN> in examples.

Need Help?

Email: support@ysdesk.com

Documentation: https://docs.ysplugins.com/ys-desk