Identity token claims

Example

A payload with every claim. Only sub and exp are required.

payload.json

{
  "sub": "user_8421",
  "email": "maria@example.com",
  "name": "Maria Lopez",
  "attributes": {
    "plan": "pro",
    "seats": 12
  },
  "exp": 1893456000
}

Header

Iris accepts only HS256. A token signed with another algorithm fails with 401.

header.json

{ "alg": "HS256", "typ": "JWT" }

Claims

substringRequired#

Your user's id in your product. Use an id that never changes, not the email. Iris finds the contact by it.

Length: 1 to 255 characters

Example: sub: "user_8421"

emailstring (email)Optional#

The contact's email. Agents see it on the contact.

Length: up to 320 characters

Example: email: "maria@example.com"

namestringOptional#

The contact's name. Agents see it in the inbox and on the contact. Iris removes spaces at the start and the end.

Length: 1 to 200 characters

Example: name: "Maria Lopez"

attributesobjectOptional#

Contact attributes: stable facts about the contact, such as their plan or role. They stay on the contact until you send a new value. Iris checks your signature, so the browser cannot change them. Page context has no such check.

Size: up to 50 keys

Example: attributes: { plan: "pro", seats: 12 }

Show child attributesHide child attributes

<key>string | number | boolean | nullOptional#

Iris keeps the keys in the order you send them.

Key: up to 64 charactersString value: up to 500 characters

Example: plan: "pro"

expnumberRequired#

When the identity token expires. Iris rejects an expired token with 401, so give the widget a new one before then. One hour is a good default.

Format: Unix time in seconds

Example: exp: 1893456000

Updating a contact

Call Iris.identify with a new identity token. A claim you leave out keeps the stored value. A token with only sub and exp keeps the name, email and contact attributes that Iris already has.

app.js

Iris.identify({ token: newToken });