User authentication

Identity verification is a way to verify that a user interacting with a copilot is the same user as is authenticated in the application. This is required to limit user access to copilots, persist user conversation history across browser sessions, provide personalized copilot experiences, and to ensure users can only access data they are authorized to see.

Continual Access Tokens

Continual Access Tokens are JSON Web Tokens (JWTs) (opens in a new tab). They are used to verify an end user's identity and are signed using the Copilot Secret Key key that is shared between your backend application and Continual.

About Continual access tokens

All Continual access tokens must include the following information:

• The Copilot Id, which is the id of the copilot this access token is for.
• An Identity grant, which is the identity of the user who is accessing this copilot

The secret key is associated with the copilot and is used to sign the Continual access Token and verify it is associated with the target copilot. It can be found in the settings tab for your copilot.

The Copilot Id is the unique id for your copilot. It can be found in the upper right hand corner when managing your copilot.

The Identity grant sets the user id that is using the copilot. This user id must be unique among copilot users and be associated with the application user.

Time-To-Live (ttl) and Issued-At-Time (iat)

Continual access tokens must be valid when using the copilot. For security purposes, access tokens should not live indefinitely. We recommend that you set the ttl to 24 hours (86,400 seconds).

In order to revoke Continual access tokens based on creation time, it is necessary to set the iat. This is the unix time stamp (opens in a new tab) of when this access token was generated. Most JWT libraries will set this automatically.

Generating Continual access tokens

You can generate a Continual access token using a variety of libraries (opens in a new tab) that are available for most programming languages. As mentioned above the critical information to include are:

• Copilot Id set as the issuer
• User Id set as the identity grant

An example node function:

import jwt, { Algorithm, JwtHeader, JwtPayload, Secret, SignOptions } from "jsonwebtoken";
 
const generateUserAccessToken = (
  userId: string,
  copilotId: string,
  copilotSecret: string
): string => {
  const algorithm: Algorithm = "HS256";
  const ttl = 86400;
 
  const payload: JwtPayload & { grants?: { identity: string }} = {
    grants: {
      identity: userId,
    },
  };
  const header: JwtHeader = {
    typ: "JWT",
    alg: algorithm,
  };
  const signOptions: SignOptions = {
    header: header,
    issuer: copilotId,
    expiresIn: ttl,
  };
 
  return jwt.sign(payload, copilotSecret, signOptions);
};
 
const signed = generateUserAccessToken("a_user_id", "a_copilot_id", "copilot_secret")
console.log({signed});
 
const decoded = jwt.verify(signed, "copilot_secret");
console.log({decoded})

This will generate a signed JWT token that is Base64Url encoded.

Setting the access token

To set the access token for a copilot, you will create the access token for the user using a function such as the one above and set this at the <CopilotProvider /> component level:

import { CopilotProvider } from "@continual/react";
 
const copilotId = "MYCOPILOTID";
const accessToken = api.generateUserAccessToken(...);
 
<CopilotProvider
    copilotId={copilotId}
    accessToken={accessToken}
/>

Verifying Continual access tokens

Continual will verify the access token by using the secret key associated with the copilot. The signature component of the JWT is used to verify that the token has not been changed since it was generated. If the JWT cannot be verified, the copilot will not allow the user to access it.

Additionally if the JWT has expired then an expired token error will be returned and a new token will need to be generated.

Tool authorization using Continual access tokens

Tools can use Continual access tokens to authorize user access. You can read more about tool authorization in the Tools documentation.

Revoking Continual access tokens

Access tokens are time limited and will expire after a set period of time. You also can revoke all access tokens by regenerating the copilot secret key.

Disabling anonymous access

You can disable anonymous access to your copilot on the copilot Settings page. You must implement identity verification in your tool if you disable anonymous access.