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

# Provision tenants for your customers

> Use a platform API key to create, serve, and tear down a tenant per end-customer.

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](/guides/platform-patterns) 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](https://app.withsplendor.com) (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.

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

  ```bash theme={null}
  export SPLENDOR_PLATFORM_KEY="splpk.v1...."
  ```
</Tip>

## Steps

<Steps>
  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="List and look up your tenants">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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`.
  </Step>
</Steps>

## Rotating a key

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

```bash theme={null}
# 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.

<Check>
  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.
</Check>

## Related

<Columns cols={2}>
  <Card title="Build a platform" icon="sitemap" href="/guides/platform-patterns">
    Why a customer is a tenant and a content type is a dataset.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Tokens, the tenant header, and roles.
  </Card>
</Columns>