Selah
docs

Integration guides by tenant type

Platform

This guide is for a company whose product is agents serving many of their own customers. You embed Selah so each of your customers gets governance. You hold one parent account and create a sub tenant for each customer through the API. When the engine needs a human, it sends a webhook to your system and you resolve it inside your own product; Selah stores nothing about that escalation.

Read Getting started and Agent Operating Procedures and the Shadow AOP Ledger first. Steps 1 to 4 establish the parent and the provisioning pattern. Steps 5 onward are the per customer flow and the data plane.

Step 1. Create your parent tenant

In the dashboard, create your company as a tenant of type platform. The platform type unlocks nested tenancy, sub tenant provisioning, and outward escalation by webhook.

Step 2. Create a provisioning key

So your system can create sub tenants programmatically, create a provisioning key for the parent:

curl -s https://api.selahcore.com/v1/admin/tenants/$PARENT_TENANT_ID/provision-key \
  -H "X-API-Key: $SELAH_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{}'

Store the returned key as a secret. This key provisions sub tenants under your parent. Confirm the exact response shape in the live OpenAPI.

Step 3. Register your webhook endpoint

Register the endpoint in your product that will receive escalations and events. This is how your customers experience governance, so build it into your review surface, not a side inbox. See Webhooks and holds. For platform tenants the key event is output.escalated, plus action.held.

Step 4. Build a few AOP templates

Do not author AOPs by hand for every customer. Define a few templates by customer type, each a set of packs and response AOPs, so provisioning a new customer is consistent and fast. You will apply a template when you create each sub tenant.

Step 5. Provision a sub tenant per customer

As you onboard a customer, provision a sub tenant under your parent and apply its AOPs. Conceptually:

# Create the sub tenant under the parent
curl -s https://api.selahcore.com/v1/admin/tenants \
  -H "X-API-Key: $SELAH_PROVISION_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "northwind-retail", "tenant_type": "platform", "parent_tenant_id": "'$PARENT_TENANT_ID'" }'

# Enable AOP packs and set response AOPs for that sub tenant
curl -s https://api.selahcore.com/v1/admin/tenants/$SUBTENANT_ID/packs/enable \
  -H "X-API-Key: $SELAH_PROVISION_KEY" -H "Content-Type: application/json" \
  -d '{ "pack": "retail-baseline" }'

def provision_customer(name, packs):
    sub = requests.post(f"{BASE}/v1/admin/tenants", headers=PROVISION_HEADERS, json={
        "name": name, "tenant_type": "platform", "parent_tenant_id": PARENT_TENANT_ID,
    }).json()
    sub_id = sub["id"]
    for pack in packs:
        requests.post(f"{BASE}/v1/admin/tenants/{sub_id}/packs/enable",
                      headers=PROVISION_HEADERS, json={"pack": pack})
    return sub_id

The exact create endpoint and field names should be confirmed against the live OpenAPI. The shape above reflects the nested tenancy model: a parent tenant with sub tenants, each carrying its own AOPs.

Step 6. Generate a data plane key per integration

Generate an evaluate scoped key for your platform to call the data plane on behalf of your sub tenants. How you scope keys across sub tenants depends on your architecture; confirm the pattern in the dashboard and the OpenAPI. The tenant is always resolved from the key.

Step 7. Integrate the data plane

The three calls are the same as anywhere, made on behalf of the relevant sub tenant, applying that sub tenant's AOPs. Action check:

def evaluate_action(agent_id, action, parameters, idempotency_key):
    r = requests.post(f"{BASE}/v1/evaluate", headers=HEADERS, json={
        "agent_id": agent_id, "action": action, "parameters": parameters,
        "context": {"idempotency_key": idempotency_key},
    })
    r.raise_for_status()
    return r.json()

Response check, sending the conversation thread so the model layer can judge grounding:

def validate_response(agent_id, text, thread):
    r = requests.post(f"{BASE}/v1/validate/output", headers=HEADERS, json={
        "agent_id": agent_id, "response_text": text, "context": {"thread": thread},
    })
    r.raise_for_status()
    return r.json()  # allow | block | escalate

Input check is POST /v1/gate/check, as in Getting started.

Step 8. Handle escalations by webhook

When a sub tenant needs a human, Selah does not hold the decision and does not store the conversation. It fires a webhook to your endpoint with the context, and you resolve it inside your product. A platform escalation looks like:

{
  "event": "output.escalated",
  "sub_tenant": "northwind-retail",
  "reason": "response not grounded in policy source",
  "context": { "response": "the drafted reply", "rule": "policy_grounding", "thread": [] }
}

Receive it, route it to the right reviewer in your interface, and resolve it there. Selah recorded the decision against the sub tenant for your reporting and stored none of the conversation itself. Validate webhook signatures and respond quickly; see Webhooks and holds.

Step 9. Shadow per customer type, then enforce

When you onboard a kind of customer you have not governed before, run that sub tenant in shadow first to build a Shadow AOP Ledger and learn the right AOPs, then enforce. You can manage shadow per tenant. See Going live.

Step 10. Read usage per sub tenant

Selah meters usage per tenant and per service, which gives you the basis to package governance into your own plans.

curl -s "https://api.selahcore.com/v1/admin/tenants/$SUBTENANT_ID/usage?period=month" \
  -H "X-API-Key: $SELAH_ADMIN_KEY"

A worked example

An AI customer service platform serves two hundred businesses. Each is a sub tenant. A new business signs up, your system provisions a sub tenant and applies the retail AOP template with a jurisdiction pack and a refund policy disclaimer. From its first conversation that customer has governance, and you authored nothing by hand. Later one of its agents drafts a reply that contradicts the customer's refund policy. The response check escalates, a webhook fires to your product, and your reviewer handles it in your own interface. Selah stored none of the conversation.

Checklist

  • Parent tenant created as type platform, provisioning key stored.
  • Webhook endpoint registered and wired into your review surface.
  • AOP templates defined by customer type.
  • Sub tenant provisioning automated in your onboarding.
  • Data plane integrated on behalf of sub tenants.
  • Escalation webhook handled inside your product, signatures validated.
  • New customer types shadowed into a Shadow AOP Ledger before enforcement.
  • Per sub tenant usage feeding your billing.