Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tinyinbox.co/llms.txt

Use this file to discover all available pages before exploring further.

Identity verification lets your backend tell TinyInbox who a logged-in visitor is. Use it when you want the inbox to show trusted names, emails, or user IDs instead of browser-provided details.

​
When to use it

Use signed identity when:
  • Visitors are logged in to your product
  • You want replies tied to your own user IDs
  • You need names or emails to come from your backend
For public marketing pages, browser identity is usually enough.

​
Get the site secret

Reveal the site’s identity signing secret from the dashboard. Keep this secret on your backend only. You can also fetch it from the API: 
GET /sites/{siteId}/security
Authorization: Bearer <user-session-token>

​
Sign the token

The identity token must:
  • Use the HS256 algorithm
  • Set aud to tinyinbox-widget-identity
  • Include userId or sub
  • Optionally include name, email, and siteKey
  • Expire quickly
Example backend route: 
import { SignJWT } from "jose"

export async function GET() {
  const token = await new SignJWT({
    userId: user.id,
    name: user.name,
    email: user.email,
    siteKey: "tin_your_site_key",
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setAudience("tinyinbox-widget-identity")
    .setExpirationTime("30m")
    .sign(new TextEncoder().encode(process.env.TINYINBOX_IDENTITY_SECRET))

  return Response.json({ identityToken: token })
}

​
Pass the token to the widget

const { identityToken } = await fetch("/api/tinyinbox/identity").then((res) =>
  res.json()
)

window.TinyInbox.identify({ identityToken })
You can also render the token into the widget script with the data-tinyinbox-identity attribute.

​
Rotate the secret

Rotate a site’s identity secret if it has been exposed. After rotation, update your backend environment variable. API route: 
POST /sites/{siteId}/security/rotate-identity-secret
Authorization: Bearer <user-session-token>
Existing identity tokens signed with the old secret stop working after rotation.