All articles

Refresh, Reroute and apps

Let signed-in customers use the widget without a second sign-in

Your server identifies the customer, so the customer does not sign in again.

Your customers can be signed in to your application already. Then your server can tell OHSupport who they are. We call this handoff. The customer does not write an email address, and does not sign in again. The widget shows all conversations of that customer for your brand.

How it works

Your server signs a short token for the customer with the handoff secret of your brand. The widget sends the token to OHSupport. OHSupport checks the token and gives the widget a customer session. The session is valid for 24 hours.

Get the handoff secret

  1. From your server, send a POST request to /v1/brands/<brand id>/handoff-secret with your tenant secret key.
  2. Keep the secret value from the response in your secret store.

CAUTION: OHSupport shows the secret one time only. If you lose it, send the request again. The new secret replaces the old secret, and old tokens stop working.

Sign the token

Make a JSON Web Token with the HS256 algorithm. Use the handoff secret as the key. OHSupport rejects all other algorithms. The token needs these claims:

  • aud: the brand id.
  • sub: the id of the customer in your application.
  • email: the email address of the customer.
  • name: the name of the customer. This claim is optional.
  • iat and exp: the time of issue and the time of expiry. Set exp to one hour or less after iat. We recommend 5 minutes.

Sign the token on your server. Do not sign it in the browser.

Give the token to the widget

  1. Make an endpoint on your server that returns a new token for the customer who is signed in.
  2. In the browser, get the token from that endpoint.
  3. Call OHSupport.identify with the token.
  4. When the customer signs out of your application, call OHSupport.reset.

If identify fails with 401, examine the claims aud and exp, and the secret. If it fails with 400, the brand has no handoff secret. We recommend this procedure for Obsidian Heron products such as Refresh and Reroute.