Authentication (JWTs)
Learn how to generate JSON Web Tokens (JWTs) for automatic authentication when using the Agent JS API and/or IFrame embeds.
Last updated
Was this helpful?
Learn how to generate JSON Web Tokens (JWTs) for automatic authentication when using the Agent JS API and/or IFrame embeds.
Last updated
Was this helpful?
JSON Web Tokens (JWTs) can be used for automatic authentication when using the and/or . For example, adding a JSON Web Token (JWT) as a query parameter allows the IFrame embed to load with the specified user already logged in.
There's no need to create the specified user ahead of time - this is all done automatically through use of JWTs.
The JWT is a token that carries information about which account it is, and who the specified user is. It is cryptographically signed by a RS256 private key on your backend. You will share with us the associated public key in your so that we can verify the request is from you and auto-authenticate the specified user to your account.
The JWT you create and sign should contain the following claims:
Claim
Description
iat required
Issued at time - this should be the time you created the JWT.
exp required
Expiry time - after this time we won't accept this JWT any more. How long JWTs you create last for is up to you, but we would recommend expiring them no more than a day after creation for security purposes.
aud required
Audience - must always be https://cobrowse.io.
iss required
sub required
Subject - The email of the support agent that you'd like to auto-authenticate. User will be automatically created if it does not yet exist.
displayName optional
Agent Display Name - The name of the support agent (may be displayed to the end user).
role optional
policy optional
Your sub and displayName claims are used for audit trail purposes. Along with the policy claim, they also scope agent access to your end-user's devices/information. This means that setting these claims as shared values between users is not recommended.
Follow these steps to generate your JWT:
Keep the private key safe, and do not change the public key in the JWT SSO text box.
Issuer - Should be the license key for your Cobrowse account which can be found at .
User role - 'administrator' or 'agent'. Used for admin-level API calls, e.g. .
Policy - Optionally limit the scope of the JWT (e.g. limiting which devices can be listed and connected to). See the for more details.
Generate an RS256 key pair by clicking the "Generate" button in the .
Sign your claims object using your private key downloaded from step 1. Find a range of JWT signing libraries at . (Video guide below.)
Add the JWT as a query parameter to the , or pass it to the .
We recorded a video showing the complete steps to generate a RS256 private key, use it to sign a JSON object with the required claims, and use it as a query parameter to automatically authenticate the specified user. Hope it is helpful!
We also recorded a video showing how to use the JWT Policy claim to restrict the scope of the JWT to a filtered set of devices.