​
Installing from npm

You can install the Paragon SDK with npm:

npm install @useparagon/connect

The SDK can be imported in your client-side JavaScript files as a module:

import { paragon } from '@useparagon/connect';

For on-premise/single-tenant users:

If you are using an on-prem/single-tenant instance of Paragon, you can call the .configureGlobal function to point the SDK to use the base hostname of your Paragon instance.

import { paragon } from '@useparagon/connect';

// If your login URL is https://dashboard.mycompany.paragon.so:
paragon.configureGlobal({
    host: "mycompany.paragon.so"
});

​
Setup

Before using the Paragon SDK, you’ll need to set up your application to verify the identity of your users to the SDK.

Paragon verifies the identity of your users using the authentication system you’re already using, including managed services like Firebase or Auth0. Some backend code may be required if your application implements its own sign-in and registration.

​
Generating tokens with your backend

If your backend server will generate JWTs for Paragon, you’ll first need to complete the following steps:

​
1. Generate a Paragon Signing Key

To generate a Signing Key, go to Settings > SDK Setup in your Paragon dashboard. You should store this key in an environment secrets file. For security reasons, we don’t store your Private Key and cannot show it to you again, so we recommend you download the key and store it someplace secure.

A unique Signing Key is generated for each environment. To learn more about the environments supported by Paragon, visit our Releases documentation.

Note: Signing keys never expire. However, generating a new signing key for the same environment will automatically invalidate the previous one.

​
2. Generate a Paragon User Token

Next, you’ll need to generate a Paragon User Token for each of your authenticated users. To do this, you’ll need a library in your target language to sign JWTs with RS256. You can find one in your language at https://jwt.io/.

If your application is a fully client-rendered single-page app, you may have to create and use an additional API endpoint to retrieve a signed JWT (or reuse an existing endpoint that handles authentication or user info).

The signed JWT/Paragon User Token minimally must include the sub, iat, and exp claims:

JavaScript
{
	// Uniquely identifying key for a user or their company
	"sub": "the-user/company-id",

	// Issue timestamp, should be the current time
	"iat": 1608600116

	// Expiry timestamp for token, such as 1 hour from time of signature (iat)
	"exp": 1608603716
}

Just for testing: Generating one-off JWTs

Use the Paragon JWT Generator to generate test JWTs for your development purposes. In production, static tokens should never be used.

​
3. Call paragon.authenticate()

You’ll call paragon.authenticate in your view with a JWT signed by your backend using the library chosen in Step 2. This JWT is the Paragon User Token.

await paragon.authenticate(
	// Your Paragon Project ID
	"38b1f170-0c43-4eae-9a04-ab85325d99f7",

	// See Setup for how to encode your user token
	"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey..."
);

The paragon.authenticate function is Promiseable and resolves when the SDK has successfully authenticated your user. Note that other functions, like paragon.connect, may not work as expected until this Promise has resolved.

Example Implementation: A Node.js and Express app using Handlebars view templating

  1. Adding middleware to sign the JWT and include it in the response context

    // server.js - Adding middleware to sign an authenticated user's token
const jwt = require('jsonwebtoken');

app.use((req, res, next) => {
  if (!req.user) {
    return next();
  }
  // JWT NumericDates specified in seconds:
  const currentTime = Math.floor(Date.now() / 1000);
  res.locals({
    paragonToken: jwt.sign(
      {
        sub: req.user.id,  // Your user's or their company's ID
        iat: currentTime,
        exp: currentTime + (60 * 60), // 1 hour from now
      },
      process.env.PARAGON_SIGNING_KEY,
      {
        algorithm: "RS256",
      }
    ),
  });
  next();
});

  2. Use the paragonJwt set in context within the view template, with a call to paragon.authenticate:

    // layout.hbs - Include paragon.authenticate call in the view template
<body>
	<script type="text/javascript">
	  paragon.authenticate("project-id", "{{ paragonToken }}").then(() => {
		  // paragon.getUser() will now return the authenticated user
		});
	</script>
</body>

​
Using a managed authentication service

If you already use an authentication service like Auth0, Firebase, or a JWKS-compatible authentication server, you can set up your Paragon project to use tokens generated by that service by navigating to Settings > SDK Setup and selecting a provider.

Since Paragon uses a JSON Web Token (JWT) to encode and validate user identity, many managed services will already have a token that you can pass directly to Paragon.

You’ll need to provide Paragon with your Auth0 Tenant Domain, which ends with .auth0.com. Example: https://<YOUR_TENANT>.auth0.com.

If you have a domain alias for your tenant domain, use the domain alias instead.

The Auth0 ID token can be used directly as the Paragon User Token.

Auth0 provides comprehensive docs on retrieving the ID token in various contexts. An example of this, using their single page app SDK:

auth0.getIdTokenClaims().then((claims) => {
  await paragon.authenticate("project-id", claims.__raw);
});