<aside> 💡 User vs. Enduser: As a developer, or a user of the Tellescope web app, your account type is User. Endusers, often “patients”, are your clients - those who receive external communication from your team, fill out forms, use your app or website, etc.

</aside>

Why Authenticate Endusers?

You can build a complete authentication system for your application using Tellescope. If you already have an authentication system in place, you can generate tokens for your Endusers that allow them to access the Tellescope API directly from the client side. This is a convenience that allows them do things like send secure messages, join video calls, and fill out forms directly. Otherwise, to keep your API Key secret, you would need to write backend code that routes each client request to the Tellescope API.

Usage in React

In React, we leverage the WithEnduserSession Context Provider to manage enduser authentication. EnduserProvider is used to manage state when loading data from the Tellescope API.

import { EnduserProvider, WithEnduserSession } from "@tellescope/react-components"

const App = () => (
	<WithEnduserSession sessionOptions={{ 
    businessId: 'BUSINESS_ID_HERE', // found in your Settings page 
		authToken: "auth_token_here", // optional, include a generated enduser authToken here
    handleUnauthenticated: async () => {
			// optional, called when a request is performed with an expired auth token
		},
  }}>
  <EnduserProvider>
    <Routing />
  </EnduserProvider>
  </WithEnduserSession>
)

In children of WithEnduserSession, it is easy to access an instance of the enduser SDK.

import { useEnduserSession } from "@tellescope/react-components"

const AuthenticationRouter = () => {
	const session = useEnduserSession()

  return (
    !session.authToken 
	    ? <UnauthenticatedAppRoutes />
      : <AuthenticatedAppRoutes />
  )
}

Integrating With An Existing Authentication System

Creating an Enduser

When people register for your app or service, you should create a corresponding Enduser in Tellescope using the API. You can assign your own unique identifier as part of the externalId field. If you already have a database of accounts, you can create a batch of Endusers in Tellescope as part of an initial migration. Moral of the story, an Enduser must exist in Tellescope before they can be authenticated.

Generating an authentication token

When an Enduser logs into your application using your existing authentication system, you can in turn generate an enduser authentication token for the Tellescope API by using the Generate authToken endpoint. When this is included in request headers as a Bearer token, it will grant access to the enduser’s resources.

Integrating an existing authentication system with React

After generating an authentication token from your API, the client will want to store it for future requests to Tellescope. This can be done as follows in React.

<aside> 💡 Make sure that useEnduserSessionContext is called within a child of WithEnduserSession. See above.

</aside>

import { 
  Flex,
  useEnduserSessionContext 
} from "@tellescope/react-components"

export const Login = () => {
  const { enduserSession, updateLocalSessionInfo } = useEnduserSessionContext()

  /** 
	* Replace enduserSession.authenticate with a custom handler for your API
  *   which returns the result of /v1/generate-enduser-auth-token
  */ 
  return (
    <Flex flex={1}>
      <EmailAndPasswordInput
        onSubmit={async ({ email, password }) => {
          try {
            const { authToken, enduser } = await enduserSession.authenticate(email, password) 
            updateLocalSessionInfo(enduser, authToken)
          } catch(err: any) {
            return err?.message ?? 'An unknown error occurred'
          }
        }}
      /> 
    </FLex>
  )
}