Skip to main content
Tenants represent your customers within the Nova Embed API. Each tenant has isolated data and separate usage metrics.

​
Tenant Header

Every request must include the tenant identifier: 
X-Tenant-Id: <your_customer_id>
This should be your internal customer/account ID - use a stable identifier that won’t change.

​
Just-in-Time Provisioning

Tenants are created automatically when we receive a request with a new X-Tenant-Id. No pre-registration required.
This works because billing happens at the integrator level (your organization), not per-tenant. You handle billing your own customers however you choose.

​
What Tenants Provide

  • Data isolation: Scores, criteria, and question sets are scoped per tenant
  • Per-customer metrics: Usage, success rates, and costs broken down by customer
  • Queryability: Filter API responses and reports by tenant
  • Compliance: Customer-specific audit trails for data governance

​
Choosing a Tenant ID

Use an identifier that is:
RequirementWhy
StableWon’t change if the customer updates their name or settings
UniqueDistinct across all your customers
ConsistentSame ID used across all API calls for that customer
Good examples:
  • cust_a1b2c3d4 (your internal customer ID)
  • org-12345 (your organization/account ID)
  • A UUID you generate per customer
Avoid:
  • Customer names (can change)
  • Email addresses (can change)
  • Sequential integers (might expose customer count)

​
Example Integration

// When a customer enables Nova scoring
async function enableNovaScoring(customerId: string, jobId: string) {
  // Use your existing customer ID as the tenant ID
  const tenantId = customerId;

  // All Nova API calls for this customer use the same tenant ID
  const headers = {
    'Authorization': `Bearer ${process.env.NOVA_API_KEY}`,
    'X-Tenant-Id': tenantId,
    'Content-Type': 'application/json',
  };

  // First request with a new tenant ID auto-provisions the tenant
  const response = await fetch(`https://embed.nova.dweet.com/v1/jobs/${jobId}/criteria-generations`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ jobContext: {...} }),
  });
}

​
Tenant Lifecycle

Tenants persist indefinitely. There’s no need to “delete” tenants - they simply have no activity if a customer stops using Nova.

​
Multi-Environment Considerations

Sandbox and production environments have separate tenant namespaces. The same tenant ID in sandbox vs production refers to different isolated data stores.
This means you can safely test with real customer IDs in sandbox without affecting production data.