#Identity flows

A known visitor is a JWT signed with your private key, verified by Vatio with your public key, and forwarded to your API as $auth.token when a private tool runs. It reaches Vatio on the web, where your page renders it onto the widget, and on WhatsApp and Instagram, where the contact brings it back from your sign-in page (On WhatsApp and Instagram).

The diagram below is Mermaid so that they read the same in a browser, in the Markdown twin of this page and to a coding agent.

#Keys and credentials

$auth.token is always the identity JWT. The publishable token names the workspace, not the person, and never reaches your backend.

#Web

sequenceDiagram
  autonumber
  participant B as Your backend
  participant W as Widget / SDK
  participant V as Vatio
  participant A as Your API
  B->>W: page with data-token=vatpub_… and data-visitor-token=JWT
  W->>V: POST /api/visitor/v1/:ws/chats (Bearer vatpub_, visitor_token)
  V->>V: origin allowed for the token, rate limit, verify JWT with identity.pub
  V->>V: store the JWT, write name/email/phone_number onto the contact
  V-->>W: chat_token (12 h)
  W->>V: messages (Bearer chat_token)
  V->>V: private tool: verify the stored JWT again (exp)
  V->>A: Authorization: Bearer $auth.token
  A->>A: verify with your key

• A visitor who signs in mid-conversation: the page calls VatioWidget.identify(jwt), and the SDK posts it to /api/visitor/v1/:ws/chats/:id/identify.
• A JWT with a different sub answers identity_changed, and the SDK starts a new conversation. One person never sees another's.
• No JWT means an anonymous chat. Private tools answer that they could not confirm who the visitor is.
• Vatio never mints a token: your backend signs it. See On the web.

#Where to go next

• Sessions and channels: rendering the token, and signing in mid-conversation.
• Private tools: access: private and the $auth.* placeholders.
• vatio-sdk: the Ruby gem that signs and verifies the JWT.