Skip to main content
POST
/
api
/
v5
/
sessions
/
visitor
Register a visitor session
curl --request POST \
  --url https://apix.us.amity.co/api/v5/sessions/visitor \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "deviceId": "<string>",
  "deviceInfo": {
    "kind": "ios",
    "model": "<string>",
    "sdkVersion": "<string>"
  },
  "authSignature": "<string>",
  "authSignatureExpiresAt": "2024-12-31T23:59:59Z"
}
'
{
  "accessToken": "<string>",
  "issuedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "users": [
    {
      "userId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "_id": "<string>",
      "path": "<string>",
      "userInternalId": "<string>",
      "userPublicId": "<string>",
      "roles": [
        "<string>"
      ],
      "permissions": [
        "MUTE_CHANNEL"
      ],
      "displayName": "<string>",
      "profileHandle": "<string>",
      "description": "<string>",
      "avatarFileId": "<string>",
      "avatarCustomUrl": "<string>",
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "metadata": {},
      "isGlobalBan": true,
      "isBrand": true,
      "isDeleted": true
    }
  ],
  "roles": [],
  "files": [],
  "lastCachePurge": "2023-11-07T05:31:56Z",
  "userType": "visitor"
}

Headers

​
x-api-key
string
required

API key for network authentication

Body

application/json

Information about visitor user and devices that they use to connect. Visitor users have read-only access and cannot perform write operations.

If deviceId haven't been used before, a new visitor user will be created.

accessToken expires in 30 days by default.

​
deviceId
string
required

Unique identifier for the device

Required string length: 1 - 150
​
deviceInfo
object

Optional device information for analytics and debugging

​
authSignature
string

Authentication signature for visitor user (required for secure visitor sessions only)

The signature must be created using HMAC-SHA256 and returned as hexadecimal:

HMAC-SHA256(payload, applicationSecret)

Steps to generate:

  1. Create HMAC-SHA256 hash using payload as message and applicationSecret as key.

    Payload format: deviceId=deviceId&authSignatureExpiresAt=authSignatureExpiresAt

    Device id and authSignatureExpiresAt must match the values sent in the request.

  2. Convert the resulting hash to hexadecimal string (64 characters)

The applicationSecret can be found in the console at Feature settings > User section when enabling secure visitor sessions.

Required string length: 64
​
authSignatureExpiresAt
string

ISO 8601 timestamp indicating when the authSignature expires (required for secure visitor sessions only)

Example:

"2024-12-31T23:59:59Z"

Response

Session Information with access token and user data

​
accessToken
string
required

JWT access token for API authentication

​
issuedAt
string<date-time>
required

Token issuance timestamp

​
expiresAt
string<date-time>
required

Token expiration timestamp

​
users
object[]
required

User information array

​
roles
object[]

User roles array

Example:
[]
​
files
object[]

Associated files array

Example:
[]
​
lastCachePurge
string<date-time>

Date of the last cache purge

​
userType
enum<string>

Type of user (e.g., signed-in, visitor, bot)

Available options:
signed-in,
visitor,
bot
Example:

"visitor"