Learn how to embed the Craft.io Feedback Widget in your application and configure secure authentication so users can submit feedback without signing in separately to Craft.io.

The Feedback Widget uses your application's existing authentication system to identify users. Integration requires adding a JavaScript snippet to your application and implementing a server-side endpoint that generates signed authentication tokens.

This guide covers the technical implementation. For instructions on creating and configuring widgets in Craft.io, see Collect Feedback Directly from Your Product and Existing Systems into Craft.io.

Before you begin

You'll need:

An existing Feedback Widget configured in Craft.io.
The installation snippet and Widget ID, available under Feedback Portal Settings → Feedback Widgets → Installation.
An authentication secret key generated under Feedback Portal Settings → Feedback Widgets → Authentication.
A server that can identify users through your application's existing authentication system.

💡 Important: The Feedback Widget requires authenticated users. Anonymous submissions aren't supported.

1. Add the widget to your application

In Craft.io, navigate to Feedback Portal Settings → Feedback Widgets and scroll to Installation.

The Installation section provides the JavaScript snippet and button markup for your configured widgets.

Add the installation script

Copy the provided script and add it to your application's HTML.

Example:

<script
  src="https://static-content.craft.io/widget/us/v1.js"
  data-portal="YOUR_PORTAL_ID"
  data-token-url="/craft-widget-token"
  async>
</script>

Replace the placeholder values with your configuration.

Attribute	Description
`src`	URL of the Craft.io widget script.
`data-portal`	Your Feedback Portal's unique identifier.
`data-token-url`	The endpoint your application uses to generate authentication tokens.

💡 Note: Copy the script directly from Craft.io rather than using the example URL above. The script URL varies depending on your hosting region.

Add a feedback button

Place the following markup wherever you want users to access the widget:

<button data-craft-widget-id="YOUR_WIDGET_ID">
  Share Feedback
</button>

Replace YOUR_WIDGET_ID with the ID generated when you created the widget.

When a user clicks the button, the feedback form opens within your application.

You can add multiple widgets using different Widget IDs. Only one installation script is required per page.

2. Configure authentication

The Feedback Widget uses JSON Web Tokens (JWTs) to securely identify users without requiring a separate Craft.io login.

When an authenticated user opens the widget:

The widget requests an authentication token from the endpoint specified in data-token-url.
Your server identifies the user through their existing authenticated session.
Your server generates a signed JWT containing the user's identity.
The endpoint returns the token to the widget.
Craft.io validates the token and associates submitted feedback with that user.

Your endpoint must be accessible from the user's browser. If it's hosted on a different origin, configure the appropriate Cross-Origin Resource Sharing (CORS) permissions.

JWT requirements

Tokens must be signed using HS256 and the authentication secret key generated in Craft.io.

Include the following claims:

Claim	Required	Description
`sub`	Yes	Unique user identifier from your application, provided as a string.
`email`	Yes	User's email address.
`iat`	Yes	Token creation timestamp, in Unix seconds.
`exp`	Yes	Token expiration timestamp, in Unix seconds.
`name`	No	User's display name.
`company`	No	User's company name, subject to your Feedback Portal's company configuration.

Tokens must have a validity period of no more than one hour. We recommend using a shorter expiration, such as 15 minutes.

💡 Note: If you include the optional company claim, the company must already exist in your Feedback Portal. Company handling also depends on whether your portal is public or restricted.

💡 Building a Pass-through Identity integration? This same JWT format authenticates Pass-through Identity API requests. See the Implementing Pass-through Identity in Your Application — Developer Guide for the submission endpoints and request examples.

3. Implement the authentication endpoint

Your application must provide an endpoint that generates a JWT for the currently authenticated user.

The following example uses Node.js.

import crypto from 'node:crypto';

const b64u = (input) =>
  Buffer.from(input).toString('base64url');

function craftWidgetToken(user, secret) {
  const now = Math.floor(Date.now() / 1000);

  const header = b64u(JSON.stringify({
    alg: 'HS256',
    typ: 'JWT'
  }));

  const payload = b64u(JSON.stringify({
    sub: String(user.id),
    email: user.email,
    name: user.fullName,
    iat: now,
    exp: now + 900
  }));

  const signature = crypto
    .createHmac('sha256', secret)
    .update(`${header}.${payload}`)
    .digest('base64url');

  return `${header}.${payload}.${signature}`;
}

Your endpoint should return the generated token in the following format:

{
  "token": "YOUR_SIGNED_JWT"
}

For example, in an Express-style application:

app.get('/craft-widget-token', requireAuth, (req, res) => {
  const token = craftWidgetToken(
    req.user,
    process.env.CRAFT_WIDGET_SECRET
  );
  res.setHeader('Cache-Control', 'no-store');
  res.json({ token });
});

This example assumes your application already provides authentication middleware (requireAuth) and makes the authenticated user available through req.user.

Replace these with your application's authentication implementation.

You can use any JWT library that supports HS256 signing.

4. Keep your authentication secret secure

Your authentication secret is used to sign tokens that Craft.io trusts when identifying feedback submitters.

Follow these security requirements:

Store the secret on your server. Never include it in frontend JavaScript, HTML, or publicly accessible configuration.
Authenticate your token endpoint. Only users with a valid application session should be able to request tokens.
Use short-lived tokens. The maximum supported validity period is one hour.
Avoid caching tokens. Return responses with Cache-Control: no-store.

Rotating your secret key

You can rotate or revoke your authentication secret under Feedback Portal Settings → Feedback Widgets → Authentication.

Rotate: Generates a new secret while keeping the previous one valid for seven days, allowing time to update your server configuration.
Revoke: Immediately invalidates the existing secret.

After rotating or revoking a key, ensure your application uses the new secret to sign tokens. If the same key also authenticates a Pass-through Identity integration, update that integration too.

5. Test your integration

Once you've installed the widget and configured authentication, verify that everything works as expected.

Sign in to your application using a test account.
Click the feedback button.
Confirm that the widget opens and displays the configured feedback form.
Submit a test feedback item.
Open your Craft.io Feedback Portal and verify that the submission appears with the correct user identity.

You can also verify that the submission includes the URL of the page where the feedback was submitted.

Troubleshooting

Issue	What to check
Widget doesn't open	Verify that the installation script loads successfully and the button contains the correct Widget ID.
Authentication fails	Confirm that your endpoint returns a valid JWT signed with HS256 and the correct secret.
Token request fails	Check that the endpoint is accessible from the browser and that CORS is configured if required.
Feedback submission fails	Verify that the token hasn't expired and includes all required claims.
Submissions stop working after key rotation	Confirm that your server uses the new secret key.
Widget is unavailable	Check that the widget is active and has at least one configured category.

If the issue persists, contact Craft.io Support.

Collect Feedback Directly from Your Product and Existing Systems into Craft.io - Configure and manage your widgets in Craft.io.
Implementing Pass-through Identity in Your Application — Developer Guide - Build an API integration using the same JWT authentication.
Feedback Status Automations - Automatically update feedback statuses as connected work items progress.

Integrating the Feedback Widget into Your Application - Developer Guide