Provision tenants for your customers

This guide takes you through the full lifecycle of a customer tenant on Splendor, using a platform API key. By the end you will have created a tenant for one of your customers, served data in it, and torn it down. For the architecture behind this, read Build a platform on Splendor first.

Prerequisites

A platform API key. You mint your own — no Splendor involvement: as a tenant admin, open the Platform Keys panel in the console (or call POST /v1/admin/platform-keys) and create a key. The secret is shown once. After that you rotate and revoke your keys under /v1/platform/keys. Treat the key like a password — it can provision and read every tenant you own.

Export your key once so the examples run as-is:

export SPLENDOR_PLATFORM_KEY="splpk.v1...."

Steps

Create a tenant for a customer

The tenant id is generated by Splendor. Pass an optional external_id to map it to your own customer id (unique within your platform), so you can find it again idempotently.

curl https://api.withsplendor.com/v1/platform/tenants \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "external_id": "cus_8210"}'

The response includes the generated tenant_id (e.g. t-3f9c2a1b...). Store it against your customer record.

Serve data in the tenant

Use the same platform key plus the child’s tenant_id in the X-Splendor-Tenant-Id header to act inside that tenant — create sources, ingest, and search, exactly as a normal tenant would.

curl https://api.withsplendor.com/v1/search \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY" \
  -H "X-Splendor-Tenant-Id: t-3f9c2a1b..." \
  -H "Content-Type: application/json" \
  -d '{"text": "invoice", "datasets": ["documents"], "limit": 10}'

The key reaches only the tenants you created. Naming a tenant you do not own returns 403.

List and look up your tenants

curl https://api.withsplendor.com/v1/platform/tenants \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY"

Each entry carries the generated tenant_id, your external_id, and the tenant’s plan.

Tear a tenant down

When a customer leaves, delete their tenant. This enqueues a managed deletion job that purges the tenant’s indexed documents, semantic vectors, and staged uploads, then removes the tenant itself. It cannot be undone.

curl -X DELETE https://api.withsplendor.com/v1/platform/tenants/t-3f9c2a1b... \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY"

The call returns 202 with a deletion job. Confirm completion by fetching the tenant — once teardown finishes it returns 404.

Rotating a key

Mint a new key, deploy it, then revoke the old one — no downtime:

# Create a new key
curl https://api.withsplendor.com/v1/platform/keys \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "rotated-2026-06"}'

# Revoke the old one by id
curl -X DELETE https://api.withsplendor.com/v1/platform/keys/123 \
  -H "Authorization: Bearer $SPLENDOR_PLATFORM_KEY"

The plaintext token is returned only once, when the key is created. Store it immediately; it is never retrievable again.

If creating a tenant returns a tenant_id, a search against it returns results, and a delete returns 202, your platform integration works end to end.

Build a platform

Why a customer is a tenant and a content type is a dataset.

Authentication

Tokens, the tenant header, and roles.

Get started

Core concepts

Guides

Build a platform

Roles, permissions & plans

Platform reference

Provision tenants for your customers

Prerequisites

Steps

Rotating a key

Build a platform

Authentication

​Prerequisites

​Steps

​Rotating a key

​Related

Build a platform

Authentication

Prerequisites

Steps

Rotating a key

Related