Authentication flow

Document Engine uses the JSON Web Token(opens in a new tab) (JWT) format for authentication. Your backend signs a JWT asserting that the holder of the token is allowed to access a given document. Next, it passes the JWT to your client apps that use Nutrient Android, iOS, and Web SDKs. Your app then passes its token to Document Engine to prove it has access to the claimed document.

How JWT security works

JWTs function as digitally signed contracts with built-in expiration dates. The security model relies on these key principles:

• Private key signing — JWTs are created and signed by your application’s backend using a private key that only you control.
• Public key verification — Document Engine verifies the JWT’s authenticity using the corresponding public key.
• Cryptographic security — Without access to your private key, it’s mathematically impossible to forge valid tokens.
• Stateless authorization — JWTs solve the challenge of handling authorization in distributed systems without requiring database lookups for every request.

Think of a JWT like a temporary access pass — it proves the holder has permission to access specific resources, but only for a limited time.

For production deployments, generate a new cryptographic key pair specifically for your Document Engine instance. Never use example, test, or shared keys in production environments. The private key must be stored securely and protected from unauthorized access, as anyone with access to your private key can forge valid authentication tokens.

JWT expiration and best practices

Short-lived tokens

JWTs should be configured with short expiration times to minimize security risks:

• Recommended duration — Set expiration between minutes to hours, not days.
• Default settings — Document Engine uses one-hour expiration by default.
• Custom configuration — You can adjust expiration times based on your security requirements.

Token renewal strategy

When a JWT expires, the client needs to obtain a new token to continue accessing documents:

1. Your backend generates a fresh JWT when the previous one expires.
2. The client application requests and receives the new token.
3. The new token is used for subsequent Document Engine requests.

This renewal process is by design and ensures continuous security while maintaining user access.

Security considerations

JWTs are designed to be transmitted between client and server. The token’s security comes from its cryptographic signature, not from being hidden. Similar to other authentication methods, session cookies and authentication tokens are equally visible in network traffic.

The key difference is JWTs remain valid until expiration unless explicitly revoked, while session tokens are immediately invalidated upon logout.

Domain licensing protection

Document Engine includes additional security layers:

• Licensed domains — Only Nutrient SDKs running on licensed origins can connect to your Document Engine instance.
• Origin verification — Each request’s origin is validated against your license.

JWT revocation capabilities

While JWTs are typically stateless and valid until expiration, Document Engine provides an escape hatch for emergency situations.

Revocation API

Document Engine offers a JWT revocation API for invalidating tokens before their natural expiration.

However, using the revocation API has tradeoffs:

• Stateful operations — Each request must check the database for revoked tokens
• Performance impact — Slightly reduced performance due to additional database queries
• Storage requirements — Revoked tokens must be stored until their original expiration time
• Infrastructure costs — Increased database usage and storage needs

The security of your JWT implementation depends primarily on protecting your private signing key and following best practices for token expiration and renewal.