Skip to main content
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. Splendor enrolls your account as a platform and issues your first key; after that you manage your own keys (rotate and revoke) 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

1

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

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

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

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.