Authenticating end users in a channel

Your digital employee can act on behalf of the person in the conversation — for example, to look up their account details in your backend. To authorize those lookups, Freeday uses a user access token that identifies the end user and forwards it to your backend as a bearer credential.

What you need to do

Put the end user's access token on the channel, in the location you agree with the Freeday team (typically a custom user attribute, or a field on the chat session). If you already pass a token to your channel or chat interface today, just set it in that same place — Freeday reads it from there and uses it automatically. You don't call a Freeday API to hand the token over.

Freeday reads whatever token is currently in place each time the user sends a message, so you do not need to issue a new token per message — but the stored token must be valid when a message arrives. What that takes depends on its lifetime: a long-lived token can be set once and rotated before it expires; a short-lived token (for example, one that expires after ~30 minutes) must be kept refreshed before it expires, so an active or returning user never hits an expired token. See "Keeping the token valid" below.

Freeday never mints or refreshes the token; it only reads the value you provide and passes it through. The rest of this page explains how that works.

How Freeday receives the token

How the token reaches Freeday depends on the channel. There are two models, and both end up in the same place — attached to the conversation session:

• Freeday fetches it from the channel. You store the token on the end user in the channel (for example, as a custom user attribute on a third-party chat platform such as Freshchat). When a message comes in, Freeday reads the current value from the channel.
• You send it to Freeday. You attach the token when the conversation is started or updated (for example, in the Freeday webchat widget), or it arrives with the inbound event over the channel's webhook. Freeday reads it off the incoming request.

The Freeday team confirms which model your channel uses, and the attribute or field name to put the token in, when the integration is set up.

How it is used

1. Freeday reads the current token when the end user sends a message. On each inbound user message, Freeday reads the token that is currently in place (fetched from the channel or received on the request) and attaches it to the conversation session. This is just when Freeday reads — it reads whatever value is there at that moment, whether that is the same long-lived token every time or a value you refresh between messages.
2. Freeday calls your backend with it. When the digital employee needs user-specific data, it sends the token to your backend as an Authorization: Bearer <token> credential. Your backend identifies the user from the token — Freeday does not send a separate user identifier.

Keeping the token valid

You do not manage this per message. Freeday reads whatever token is currently in place, so the only requirement is that a valid token is in place whenever the end user might send a message. How you meet that depends on your token's lifetime:

• Long-lived token. Issue one token that stays valid for days or weeks and leave it in place, rotating it before it expires. Effectively nothing to do per conversation — it is read as-is on every message until you replace it.
• Short-lived token. If your token expires quickly — say, after ~30 minutes — keep the stored value refreshed before it expires, so an active conversation never reaches Freeday with an expired token. Because Freeday re-reads on each user message, a refreshed value is picked up on the user's next message; the main risk is the token lapsing during a quiet stretch, so refresh it on your own schedule rather than only in reaction to activity.

Whichever you use, the new value must be in place before Freeday reads it: when Freeday fetches from the channel, the stored attribute must already be current; when you send the token on the request, it must be attached to that message. A token refreshed after a message has already arrived is too late for that turn. The mental model is "keep a valid token in place," not "refresh reactively after each message."

Things to know

• Only end-user messages trigger a re-read. Freeday re-reads the token when the end user sends a message, not on agent or system activity. With a long-lived token this is irrelevant; it only matters for short-lived tokens, where a value that expires during a long silence is re-read once the user speaks again.
• A stale token fails the lookup, not the conversation. If the token has expired by the time Freeday calls your backend, that specific data lookup fails and the digital employee continues gracefully; the conversation is not dropped.
• Keep the token out of the message body. Provide it through the channel's user attribute or session field, not in conversation content, so it is not exposed in the transcript.

Contact the Freeday team to enable token-authenticated channels and agree on where the token goes for your integration.