Authenticating User Sessions

ℹ️

Only needed for production use

A sample JWT is automatically included in the provided code snippet for development.

Why JWT?

When a customer completes an import, OneSchema will pass the data through to your system. In order to know which customer the data belongs to, you must provide a JSON Web Token (or JWT) to identify the user.

This JWT should be securely generated on your server using your Client Secret each time a user performs an import. This prevents a malicious actor from uploading data while acting as another user.

You can learn more about JWT here.

JWT setup

The payload for the generated JWT must contain at least two fields:

• iss should be a string set to your Client ID
• user_id field should be a string that will allow you to find the user that performed the import in your specified Webhook endpoint, e.g., a username, an email, or a UUID. The user_id is used for user-based historical mapping. Each user should be assigned a unique user_id; The same user_id should be encoded each time that user accesses the importer.

OneSchema will treat it as an opaque value and not modify it in any way. You should sign your JWT using the HS256 algorithm and your Client Secret.

In production you should generate these tokens on your server, but the Developer Dashboard also provides a helpful JWT generator to get started with testing more quickly.

Metadata

The JWT is also the recommended way to pass any other metadata such as analytics tokens, monitoring and performance trace IDs, or anything else you might find useful. Besides the required iss and user_id you can add any arbitrary JSON. The JWT is included in validation webhook, importer webhook, and event webhook requests.