Tenant metadata is a tool to associate the tenant IDs of your customers with meaningful user data, such as external IDs, licenses, or plain-text names. This is useful if you use UUIDs or other non-readable strings as tenant IDs. With metadata, you can associate an unreadable tenant ID b3ce717c-9ee3-4c80-a3d1-de42f3563496 with the company name Apple, Inc and Stripe Customer ID cus_P5iEJpWPKP3xXI.

Tenant metadata is accessible via:

API
Job Lifecycle webhooks, except fields marked as SecureString
Tenant configs, for use in your ETL scripts
Config variables in Connector configuration
The admin panel Tenant dashboard

You can also add metadata to tenants via the widget, API or your hotglue admin panel.

How to add tenant metadata

Metadata is added per tenant. You can add any metadata field to any tenant. The API does not check metadata values against the schema, but the admin panel uses each schema field’s type when you add or edit that field. To list the fields your environment uses, set their types, and mark sensitive fields as secure, define a tenant metadata schema. Metadata can be added using the built-in tenantMetadata option in the widget. When any widget function is called with a tenantMetadata option object, the tenant ID will be associated with your chosen metadata. This is supported in the Javascript widget (hotglue.com/widgetv2.js) or in React versions ≥ 1.4.9. For example, you can add tenant metadata using the javascript HotGlue.link function as below:

HotGlue.link(tenant, flow, connector, false, {
        tenantMetadata: {
            "Name": "OpenAI", 
            "Email": "sama@openai.com"
            "Stripe ID": "cus_P5iEJpKWPP3xXl"
        }
    }
)

🚧 Note: tenantMetadata overwrites existing metadata fields When you pass tenantMetadata to the widget, hotglue overwrites your metadata object with whatever is passed to the widget. If you do not pass all metadata values to the widget, this becomes a destructive action.

Using the API

Metadata can be added with a PUT to the /metadata endpoint. Learn more about tenant metadata APIs here.

Using the admin panel

Metadata can be added directly from the hotglue admin panel. To add metadata:

Navigate to the tenant management dashboard
Click on any tenant (not the 👁 icon) to bring up the tenant management panel
Navigate to the Metadata tab
Type in a field name, type, and value
Click + to add your new metadata field

You can then configure which metadata is shown by clicking Edit Columns in your Tenant list, or edit metadata by clicking the pencil icon next to a field in your tenant management panel.

Define a tenant metadata schema

A tenant metadata schema is an optional, environment-wide list of metadata fields and their types. Each field has one of these types:

Type	Use for
`String`	Text, such as a company name or external ID
`Number`	Numeric values, such as a seat count
`Boolean`	`true` or `false` flags
`SecureString`	Sensitive text, such as an API token for your own system

The schema shapes how metadata is displayed and edited in the admin panel and marks which fields are secure. The API and widget do not check values against the schema, and changing the schema does not change values already saved on tenants.

Define the schema in the admin panel

Navigate to the tenant management dashboard.
In your Tenant list, click the Table settings button to open the column menu.
Under Schema, click Manage schema.
Click Add field, enter a field name, and choose a type. Field names must be unique and cannot be empty.
Click Save.

Schema fields appear as columns you can show in your Tenant list. When you add or edit a schema field in a tenant’s Metadata tab, the admin panel uses the type from the schema: a toggle for Boolean, a numeric input for Number, and a masked input for SecureString.

Define the schema with the API

Read the schema with a GET to /tenant/{env_id}/metadata/schema:

curl --request GET \
  --url 'https://api.hotglue.com/tenant/{env_id}/metadata/schema' \
  --header 'x-api-key: <API_KEY>'

Set the schema with a PUT to the same endpoint. The schema object maps each field name to an object with a type:

curl --request PUT \
  --url 'https://api.hotglue.com/tenant/{env_id}/metadata/schema' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --data '{
  "schema": {
    "Company": { "type": "String" },
    "Seats": { "type": "Number" },
    "Churn Risk?": { "type": "Boolean" },
    "Internal API Token": { "type": "SecureString" }
  }
}'

Both requests return the schema in the same shape:

{
  "schema": {
    "Company": { "type": "String" },
    "Seats": { "type": "Number" },
    "Churn Risk?": { "type": "Boolean" },
    "Internal API Token": { "type": "SecureString" }
  }
}

The PUT replaces the entire schema, so include every field you want to keep. hotglue rejects the request with a 400 error when schema is missing or is not an object, when a field name is empty, or when a field’s type is not String, Number, Boolean, or SecureString. If you remove a SecureString field from the schema or change its type, values already saved on tenants stay as they are, but they are no longer masked in the admin panel or removed from Job Lifecycle webhooks. Keep the field as SecureString until you remove those values from your tenants.

SecureString fields

Mark a field as SecureString when its value should not be shown or forwarded by default. For a SecureString field, hotglue:

Masks the value in the admin panel. The Tenant list shows ***, and the Metadata tab hides the value until you click the eye icon.
Removes the field from the tenant_metadata object in Job Lifecycle webhooks.

The value is still stored in plain form in the tenant config. It is still returned by the fetch tenant metadata API, is still available to ETL scripts under hotglue_metadata.metadata, and can still be used as a config variable in Connector configuration. You set a SecureString value the same way as any other metadata value, through the widget, API, or admin panel. Because hotglue matches secure fields by name, the field name in the tenant’s metadata must match the schema field name exactly.

Use metadata in config variables

Each tenant metadata field can be used as a config variable in Connector configuration. Write the field name in curly braces, exactly as it appears in the metadata, including spaces and capitalization. When a job runs, hotglue replaces the variable with that tenant’s value. For example, with this tenant metadata:

{
  "Company": "acme",
  "Internal API Token": "tok_123"
}

A Connector configuration value of exports/{Company}/{tenant} resolves to exports/acme/<tenant ID>, and a value of {Internal API Token} resolves to tok_123.

Metadata fields named tenant, tenant_id, root_tenant_id, sub_tenant_id, env_id, flow_id, job_id, external_job_id, tap, or connector do not replace the built-in value of that variable.
Empty strings, false, and 0 are not substituted. The variable stays in the configuration as written.
Values are inserted as text. Use simple values that do not contain quotes or backslashes.
SecureString fields are substituted like any other field.

Differences between tenant metadata vs. tenant config

Tenant metadata is stored in the tenant config. That means that you can technically utilize metadata in any way that you use the tenant config—for example, as flags in ETL scripts. Inside the tenant config, metadata is structured like below:

tenant-config.json

{
  "hotglue_metadata": {
    "metadata": {
      "Company": "Apple, Inc.",
      "External Id": "appleinc",
      "Website": "apple.com",
      "Contact Email": "tim@apple.com",
      "Churn Risk?": false,
      "Stripe Plan": "enterprise",
      "Stripe ID": "cus_P5iEJpWPKP3xXl"
    }
  },
  // other tenant config objects go here
}

The primary difference is that metadata is exposed in more places (webhooks, admin panel) and it cannot be nested. This makes it an excellent candidate for simple user information like plans and company names, but a poor candidate for nested configuration objects.

Properties	Tenant Config	Tenant Metadata
Supports nested objects	✅	❌
Can be managed via the admin panel or API	✅	✅
Can be managed via widget embed code	❌	✅
Sent in job lifecycle webhooks	❌	✅

Getting Started

Key Concepts

Managed authentication

Transformation

Custom Connectors

Composite MCP

Unified Schema

Environment Settings

CLI

Connectors

Tenant Metadata

How to add tenant metadata

Using the widget

Using the API

Using the admin panel

Define a tenant metadata schema

Define the schema in the admin panel

Define the schema with the API

SecureString fields

Use metadata in config variables

Differences between tenant metadata vs. tenant config

​How to add tenant metadata

​Using the widget

​Using the API

​Using the admin panel

​Define a tenant metadata schema

​Define the schema in the admin panel

​Define the schema with the API

​SecureString fields

​Use metadata in config variables

​Differences between tenant metadata vs. tenant config

How to add tenant metadata

Using the widget

Using the API

Using the admin panel

Define a tenant metadata schema

Define the schema in the admin panel

Define the schema with the API

SecureString fields

Use metadata in config variables

Differences between tenant metadata vs. tenant config