Skip to main content
POST
/
api
/
v5
/
sessions
Register a session
curl --request POST \
  --url https://apix.us.amity.co/api/v5/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "userId": "<string>",
  "deviceId": "<string>",
  "deviceInfo": {
    "kind": "ios",
    "model": "<string>",
    "sdkVersion": "<string>"
  },
  "displayName": "<string>",
  "profileHandle": "<string>",
  "authToken": "<string>"
}'
{
  "accessToken": "<string>",
  "issuedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "users": [
    {
      "_id": "<string>",
      "path": "<string>",
      "userId": "<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,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "isDeleted": true
    }
  ],
  "roles": [
    {
      "roleId": "<string>",
      "displayName": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "permissions": [
        "<string>"
      ],
      "isDeleted": false
    }
  ],
  "files": [
    {
      "fileId": "<string>",
      "fileUrl": "<string>",
      "type": "image",
      "accessType": "public",
      "altText": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "attributes": {
        "name": "<string>",
        "extension": "<string>",
        "size": 123,
        "mimeType": "<string>",
        "metadata": {
          "exif": {},
          "gps": {},
          "height": 123,
          "width": 123,
          "isFull": true
        }
      }
    }
  ],
  "lastCachePurge": "2023-11-07T05:31:56Z",
  "userType": "signed-in"
}

Headers

x-api-key
string
required

API key for network authentication

Body

application/json

Information about user and devices that they use to connect. If displayName is provided, the user's display name is updated as well.

If userId doesn't exist, a new user will be created.

authToken needs to be passed when network option is set to secure.

accessToken expires in 30 days by default.

userId
string
required

Unique identifier for the user. Cannot start with 'ADMIN_' or 'DELETED_' prefixes.

Required string length: 1 - 50
deviceId
string
required

Unique identifier for the device

Required string length: 1 - 150
deviceInfo
object

Optional device information for analytics and debugging

displayName
string

User's display name (optional, will update user if provided)

Maximum length: 100
profileHandle
string

User's profile handle (optional, will update user if provided)

Maximum length: 100
authToken
string

Authentication token from /api/v3/authentication/token or /api/v4/authentication/token (required for secure networks)

Required string length: 1 - 100

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

files
object[]

Associated files array

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:

"signed-in"

I