Identity Verification
Identity verification makes a Data Connection look up data only for the customer who is actually chatting. The customer logs in once on your own site, and Fiko remembers the link between that customer and their user ID in your system for 30 days. From then on, lookups on the connection run with that verified ID.
This is separate from how Fiko signs in to your API, which is the connection's authentication type. See Authentication Types.
Only the chatting customer's data
Fiko fills the customer's own user ID into the lookup itself. The assistant never sees this value and cannot choose it.
Fiko never sees the password
The customer logs in on your site. Fiko only receives a signed confirmation of their user ID from your server.
Log in once, remembered for 30 days
A login link expires after 10 minutes and works once. After the customer logs in, Fiko remembers them on that connection for 30 days.
Answers without asking again
When a customer's question started the verification, the AI answers that question automatically once they are verified.
What the Customer Sees
This is the flow for a customer who has not verified yet.
The customer asks something that needs their data
The AI decides to use a lookup on a connection that requires identity verification, and this customer has not verified yet (or their earlier verification has expired). Fiko does not call your API.
The AI sends a login link
The AI replies with a fixed message, not one generated by the AI model, followed by a one-time link: "To help with your account, I first need to confirm it's really you. Please log in with the secure link below. It expires in 10 minutes."
The customer logs in on your site
The link opens your own login page, the Login URL you set on the connection, with a fikoNonce parameter added. The login itself happens entirely on your site, so Fiko never sees the customer's password.
Your site sends the customer back to Fiko
After a successful login, your server redirects the customer's browser to the Callback URL with fikoNonce, externalUserId (the customer's ID in your system) and a signature. Fiko checks the signature and links the customer to that user ID.
The customer sees a confirmation
A Fiko page says "Account verified" and tells the customer they can go back to the conversation and close the page. In the chat, Fiko posts "Thanks! Your account is now verified. Let me check that for you." when a question is waiting to be answered, or "Thanks! Your account is now verified. You can continue with your question." when none is.
The AI answers the original question
Under the conditions listed below, Fiko answers the question that started the verification, so the customer does not have to ask again.
If the link has expired, was already used, or is invalid, the Fiko page says "Could not verify" and asks the customer to go back to the conversation and request a new link.
When the Link Is Sent
- The connection has Require customer identity verification turned on, and its Login URL and shared secret are set. If either is missing, Fiko does not call your API for lookups on that connection
- The customer has no verification for that connection, or the earlier one has expired
- The lookup was started by the AI. A teammate running a lookup by hand from Customer Context in a chat sees "Customer has not verified their identity yet" and is not given a link
- Each link works once and expires after 10 minutes. Even a failed attempt uses the link up
- If the customer asks again while the earlier link is less than 5 minutes old, Fiko sends that same link again instead of creating a new one
After the Customer Is Verified
Lookups use the verified ID
For every lookup on the connection, Fiko fills the value you marked as Verified customer id with the customer's user ID. If the same spot in the path could also be filled from the email or phone number saved on the customer's contact, the verified ID is used.
The question is answered automatically
Fiko schedules the normal AI Auto-Reply for the question that started the verification. It happens only when:
- AI Auto-Reply is turned on for the channel
- The conversation is not closed and not marked as spam
- The customer's original question is still among the newest messages, the customer has not sent a newer message since, and the question is less than 10 minutes old
- That question has not already been resumed
Set It Up
Setup has two parts: the settings in Fiko and a small redirect on your own site.
Create the connection first
The Verify customer identity section appears in the Settings tab of a saved connection. It is not shown for connections that use the Customer logs in themselves authentication type, and the two cannot be combined.
Turn it on and add your login page
Open the connection, go to Settings and find Verify customer identity. Switch on Require customer identity verification, then enter the Login URL, starting with https://. This is the page on your site where customers log in. Fiko sends the customer there with a fikoNonce parameter.
Save to generate the shared secret
Click Save changes so Fiko can generate a shared secret for the connection. Use Show shared secret to reveal it and copy it into your server's configuration. Regenerate secret creates a new one and the old one stops working immediately, so your system must be updated with the new one or customers cannot verify.
Copy the Callback URL
The section shows a read-only Callback URL with a Copy button. After a customer logs in, your server sends their browser to this address.
Build the redirect on your site
After your own login succeeds, redirect to the Callback URL with three query parameters: fikoNonce, exactly as you received it; externalUserId, the customer's ID in your system (1 to 255 characters); and signature, described below. Fiko's setup screen adds: always ask the customer to confirm before linking their account.
Mark the customer ID in each lookup
Open a lookup on the connection (Data Lookups tab) and go to Find the customer. Add an extra value for the customer's ID in your system, for example customer_id, and use it in the path as {customer_id}. Then tick Verified customer id on that row. Fiko fills that value in from the verified identity, and the assistant can never choose it. The Verified customer id column only appears once the connection requires verification.
The redirect your server sends
The signature is the lowercase hex HMAC-SHA256 of the nonce, a dot and the user ID, using the connection's shared secret as the key. It is always 64 characters.
signature = hex( HMAC_SHA256( sharedSecret, fikoNonce + "." + externalUserId ) ) <Callback URL>?fikoNonce=<nonce>&externalUserId=<user id>&signature=<signature>
Good to Know
Write Actions are not supported yet
On a connection that requires identity verification, Fiko rejects a Write Action proposal, and a proposal that was made earlier fails instead of running.
One link per customer and connection
Verification is stored per customer and per connection. Verifying again replaces the stored user ID and starts a new 30 days.
The shared secret is shown on demand
Admins can reveal the shared secret from the connection's Settings tab so they can configure their own server. Viewers do not see these buttons.
Troubleshooting
The customer never receives a login link?
- Check that Require customer identity verification is on and that you saved. The Login URL must be set and a shared secret generated
- Check that AI Auto-Reply is on for the channel and that the lookup has Let the assistant look this up on its own turned on
- Remember that a teammate running a lookup by hand is not given a link
The customer sees "Could not verify"?
- Each link works once and expires after 10 minutes. Ask the customer to request a new link in the conversation
- Check the signature: HMAC-SHA256 of fikoNonce + "." + externalUserId with the connection's shared secret, as lowercase hex
- If you regenerated the shared secret, update your server with the new one
- Send fikoNonce back exactly as received, with externalUserId and signature as query parameters. Fiko shows the same message for every failure, so it never reveals which check failed
The customer is verified but the AI does not answer by itself?
- Check the conditions for the automatic answer above, in particular whether the customer sent another message or more than 10 minutes passed
- The usual AI Auto-Reply checks still apply, for example when a teammate has taken over the conversation
- The customer can ask again. The lookup then runs with their verified user ID
Lookups on the connection do not run?
- If Require customer identity verification is on but the Login URL or the shared secret is missing, Fiko does not call your API for lookups on that connection
- Open the connection's Settings tab, fill in the Login URL and click Save changes