URL Integration (embed in iframe)

Parashift offers a Viewer Integration feature that allows you to embed our document viewer directly into your own web application using an <iframe>. This provides a seamless experience for users to view documents from your Parashift tenant—without leaving your platform.

What Is Viewer Integration?

Viewer Integration enables you to display a specific document from your Parashift tenant within your application using a secure, temporary token. The viewer is embedded via an <iframe> and can be fully controlled from your backend.

How It Works

The integration flow consists of the following steps:

Generate an authentication token (JWT) using your tenant’s secret key.
Embed the iframe with the token and the document ID.
The embedded viewer securely exchanges the authentication token for a bearer token.
The bearer token is then used internally by the viewer to retrieve the document.

<iframe src="https://app.parashift.io/integration?app=viewer&auth=your.temporary.token&document_id=1234"
        width="100%"
        height="600px"
        frameborder="0">
</iframe>

Required Parameters

Parameter	Description
`app`	Must be set to `viewer`
`auth`	The temporary authentication token (JWT)
`document_id`	The ID of the document you want to display

Generating the Authentication Token

The auth parameter must be a JWT (JSON Web Token) signed with your tenant’s secret key. This token is short-lived and contains minimal claims for security.

{
  "exp": 1630000000,   // Token expiration (in seconds since Unix epoch)
  "tenant_id": 1234     // Your Parashift tenant ID
}

⏱️ We recommend an expiration time of 1 minute into the future to reduce security risk.

Example in Ruby

require "jwt"

authentication_token = JWT.encode(
  {
    exp: Time.now.to_i + 60,  # Token valid for 1 minute
    tenant_id: 1234           # Your Parashift tenant ID
  },
  "your-secret-key",          # Provided by Parashift when enabling the feature
  "HS256"
)

Enabling Viewer Integration

Viewer integration must be explicitly enabled for each tenant:

Log in to the Parashift Platform as a tenant admin.
Navigate to Settings > URL Integration.
Click Enable Viewer Integration.
Copy the generated secret key and store it securely.
Use this secret to sign JWT tokens as shown above.
Construct your iframe with the signed token and document ID.

🔐 Note: This secret acts like a password. Never expose it in client-side code.

Security Best Practices

Use HTTPS at all times.
Do not expose your secret key publicly.
Keep JWT tokens short-lived and refresh them regularly.
Monitor usage and rotate your secret periodically if needed.