Skip to main content

​
API Keys

All API requests require authentication using an API key. API keys are passed via the x-api-key header in your requests. 
curl --request GET \
     --url 'https://api.hotglue.com/...' \
     --header 'x-api-key: your-api-key'
There are three types of API keys in hotglue:

​
1. Environment API Key

The Environment API Key has global permissions on your environment. Only owners and admins have access to view and manage this key.

​
2. Personal API Key

Personal API Keys are tied to individual users and have permissions based on your role in a given environment. The available roles are:
  • Admin - Full permissions across all resources
  • Developer - Read and Write access to most resources
  • Viewer - Read-only access. Cannot read non-sensitive resources
Personal API Keys are useful for programmatic access when you need permissions scoped to your user account.

​
3. Public API Key

Public API Keys are used in your widget to request public resources. These keys are designed to be used in client-side applications and have limited permissions.

​
JWT Authentication for Widgets

In addition to using a Public API Key, you should configure your widget with a JWT and enable the “Require JWT to authenticate tenant requests” settings in the hotglue dashboard (Settings > Widget). When enabled, the Public API Key alone cannot be used to perform tenant-specific tasks --- a valid JWT must also be provided.

​
Generate a Private Signing Key

To generate your private signing key, head to the environment settings page and press Generate private key under the API Keys section:
Do not share this private signing key!For security purposes, hotglue does not store your private signing key. Keys are unique to every hotglue environment and can only be generated by an admin.
Store this private signing key securely in your backend environment variables.

​
Creating a JWT

Once you have a private signing key, you can generate a JWT from your backend to make secure requests to the hotglue API. In JavaScript, you can do this with: 
const jsonwebtoken = require('jsonwebtoken');
const currentTime = Math.floor(Date.now() / 1000);

const tenantId = "unique-tenant-identifier";

const token = jsonwebtoken.sign(
  {
    sub: tenantId,
    iat: currentTime,
    exp: currentTime + (60 * 60), // 1 hour from now
  },
  Buffer.from(process.env['HOTGLUE_SIGNING_KEY'], "base64").toString("utf8"),
  {
    algorithm: "RS256",
  }
);

​
Using the JWT in Widget V2

When launching the widget, you can pass the JWT using the options parameter: 
// Generate the JWT in your backend using the signing key
const jwt = getJwt();

// Launch the widget
HotGlue.open("tenant-id", {
  jwtToken: jwt
});

​
Using the JWT in Widget V3

When using Widget V3 with React, you can pass the JWT directly to the useHotglue hook: 
import { useHotglue, Widget } from "@hotglue/widget";

export default function WidgetLauncher() {
  const tenantId = "MY-TENANT-ID";
  // Generate the JWT in your backend using the signing key
  const jwt = getJwt();
  
  const { openWidget } = useHotglue({
    tenantId,
    environmentId: process.env.NEXT_PUBLIC_HOTGLUE_ENV_ID,
    apiKey: process.env.NEXT_PUBLIC_HOTGLUE_PUBLIC_KEY,
    jwtToken: '<TENANT SCOPED JWT>'
  });

  return (
    <div>
      <Widget />
      <button onClick={() => openWidget(tenantId)}>Open Widget</button>
    </div>
  );
}
For vanilla JavaScript, you can pass the JWT when initializing the Hotglue instance: 
// Generate the JWT in your backend using the signing key
const jwt = getJwt();

const hotglue = new Hotglue({
  tenantId: 'tenant-123',
  environmentId: '<ENV ID>',
  apiKey: '<PUBLIC API KEY>',
  jwtToken: '<TENANT SCOPED JWT>'
});

​
Using the JWT in API Requests

Sensitive API endpoints allow you to pass the JWT as a query parameter to access sensitive data on behalf of a tenant while using your Public API Key: 
curl --request GET \
     --url 'https://api.hotglue.com/env_id/flow_id/tenant_id/linkedSources?token=jwt' \
     --header 'Accept: application/json' \
     --header 'x-api-key: public_api_key'