> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hotglue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```shell theme={null}
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:

<Warning>
  **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.
</Warning>

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:

```javascript theme={null}
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](https://docs.hotglue.com/docs/embed-hotglue-javascript-reference#options):

```javascript theme={null}
// 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:

```jsx theme={null}
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:

```javascript theme={null}
// 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:

```shell theme={null}
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'
```