Authentication

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 Secret API Key

The Environment Secret API Key has global permissions on your environment. Only 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",
  }
);

Scoping a JWT

You can limit what a JWT is allowed to do by adding an optional scopes claim.

No scopes claim: the JWT keeps full tenant access, exactly as before.
With a scopes claim: it must be a list of strings, and it must include every scope the endpoint requires.

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

Here are examples of common scopes that apply to tenant endpoints:

Scope	Grants
`linked_connector.read`	List a tenant’s linked sources, targets and connectors
`linked_connector.write`	Link and update a tenant’s sources, targets and connectors
`linked_connector.delete`	Unlink a tenant’s sources, targets and connectors
`linked_connector_catalog.read`	Include the catalog when listing linked connectors (`?catalog=true`)
`linked_connector_secrets.read`	Include credentials when returning a linked connector’s config. Without it, secrets are left out
`connector_metadata.read`	Include connector metadata when listing linked sources (`?metadata=true`)
`connector_state.delete`	Reset a linked connector’s state
`discover.read`	Poll a discover run
`discover.write`	Start a discover run
`jobs.read`	List jobs and read job status
`schedule.read`	Read a tenant’s job schedule
`tenant_mapping.read`	Read a tenant’s mapping
`tenant_mapping.write`	Update a tenant’s mapping

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>
  );
}

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
});

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

Tenant-scoped API endpoints allow you to pass the JWT as a bearer token to access 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' \
     --header 'Accept: application/json' \
     --header 'x-api-key: public_api_key' \
     --header 'Authorization: Bearer <TENANT SCOPED JWT>

hotglue API

V1 flows (legacy)

V2 Flows

Connectors

MCP

API Keys

1. Environment Secret API Key

2. Personal API Key

3. Public API Key

JWT Authentication for Widgets

Generate a Private Signing Key

Creating a JWT

Scoping a JWT

Using the JWT in Widget V3

Using the JWT in Widget V2

Using the JWT in API Requests

​API Keys

​1. Environment Secret API Key

​2. Personal API Key

​3. Public API Key

​JWT Authentication for Widgets

​Generate a Private Signing Key

​Creating a JWT

​Scoping a JWT

​Using the JWT in Widget V3

​Using the JWT in Widget V2

​Using the JWT in API Requests

API Keys

1. Environment Secret API Key

2. Personal API Key

3. Public API Key

JWT Authentication for Widgets

Generate a Private Signing Key

Creating a JWT

Scoping a JWT

Using the JWT in Widget V3

Using the JWT in Widget V2

Using the JWT in API Requests