Manage multiple clients (multitenant)

​

Model A: one key per client (recommended)

1. Create an account for that client with an email and a password, on an address you control and use for that client only: a gmail.com address, or a domain used only by your client accounts (not your agency’s own domain and not the client’s, where the app suggests joining existing teams). If sign-up fails for that address, use another one.
2. Finish or skip onboarding (the app opens Settings only after it), then create a key under Settings → API keys.
3. With that key, call GET /v1/workspaces. It must list nothing, or only the workspace that onboarding creates when you send its starter message. Anything else means you are signed in to another account: revoke the key and start again.
4. Create a workspace for that client with the key (POST /v1/workspaces) and store its id next to the key. Do not delete that workspace in the app: it lets you check later that a new key was created by that client’s account. It does not show whether the organization changed, since the workspace moves with the account: step 7 of the departure procedure below covers that.

1. Take back their access to the account’s mailbox and to any Google account on that address.
2. Reset the password with Forgot password on the sign-in page.
3. Ask the Retriever team to end the sessions still open and to remove the Google sign-ins linked to the account: resetting the password does neither. Wait for the team’s confirmation, then 5 more minutes.
4. Replace the key your integration uses, as above.
5. Revoke every other key of the account, including the MCP · … ones, then list the keys again: only the new one must be left.
6. Revoke the share links you no longer want: open each shared table, since there is no list of links (copies already made from a link stay, with every table of the workspace). Also check the CRM connection, scheduled runs and signals they set up.
7. On the team page, check that the client account is the only member, that it is an admin, and that no invitation or join request is pending. Then check what the team page cannot show: GET /v1/workspaces, through every page, must still include the workspace you stored for that client and list only workspaces you know (an unknown one can mean the organization has changed, or that someone created it from the account: find out which), and the credit balance and the company brief must be what you expect (they are lost when the account is moved to another organization). If anything differs, stop and contact the Retriever team.

// tenants.mjs
import { decrypt } from "./kms.mjs"; // your secrets vault

export function retrieverFor(tenant) {
  const key = decrypt(tenant.retrieverApiKeyEncrypted);
  return async (path, { method = "GET", body, headers = {}, retries = 5 } = {}) => {
    for (let attempt = 0; ; attempt++) {
      const res = await fetch(`${process.env.RETRIEVER_API_URL}${path}`, {
        method,
        signal: AbortSignal.timeout(60_000),
        headers: {
          Authorization: `Bearer ${key}`,
          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
          ...headers,
        },
        body: body !== undefined ? JSON.stringify(body) : undefined,
      });
      if (res.ok) return res.json();
      if (res.status === 429 && attempt < retries) {
        await res.body?.cancel(); // free the connection before waiting
        const retryAfter = Number(res.headers.get("retry-after"));
        await new Promise((resolve) => setTimeout(resolve, (retryAfter > 0 ? retryAfter : 5) * 1000));
        continue;
      }
      const payload = await res.json().catch(() => ({})); // a 5xx body may not be JSON
      throw new Error(`[tenant ${tenant.id}] ${res.status} ${payload.error?.code ?? (res.statusText || "error")}`);
    }
  };
}

// in an HTTP handler
const retriever = retrieverFor(req.tenant);
const run = await retriever("/v1/runs", { method: "POST", body: { prompt: req.body.prompt } });

​

Model B: one key, one workspace per client

import os, requests

API = os.environ["RETRIEVER_API_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['RETRIEVER_API_KEY']}"}

# When provisioning the tenant
def provision(tenant):
    res = requests.post(f"{API}/v1/workspaces", headers=HEADERS, json={"name": f"tenant:{tenant.id}"}, timeout=30)
    res.raise_for_status()
    tenant.retriever_workspace_id = res.json()["id"]
    tenant.save()

# On each run: ALWAYS the current tenant's workspace
def create_run(tenant, prompt, request_id):
    res = requests.post(
        f"{API}/v1/runs",
        headers={**HEADERS, "Idempotency-Key": f"{tenant.id}:{request_id}"},
        json={"prompt": prompt, "workspace_id": tenant.retriever_workspace_id},
        timeout=30,
    )
    res.raise_for_status()
    return res.json()

# Verify ownership BEFORE using an id from the end user
def assert_run_owned(tenant, run_id):
    run = requests.get(f"{API}/v1/runs/{run_id}", headers=HEADERS, timeout=30).json()
    if run.get("workspace_id") != tenant.retriever_workspace_id:
        raise PermissionError("run does not belong to tenant")
    return run

def assert_table_owned(tenant, table_id):
    table = requests.get(f"{API}/v1/tables/{table_id}", headers=HEADERS, timeout=30).json()
    if table.get("workspace_id") != tenant.retriever_workspace_id:
        raise PermissionError("table does not belong to tenant")
    return table

• Exclusions, credits and contact unsubscribes are shared across all your clients. One client’s customers on the exclusion list are excluded for every client, and so are their employees in people searches. One client’s unsubscribe blocks that contact for all of them.
• The organization’s company brief (the company description and ideal customer profile set in the app) and its company documents are shared: every POST /v1/runs run gets yours. Go jobs do not use them.
• Messaging skills are shared.
• Email and phone answers found in the last 7 days are reused across the organization: a contact found for one client comes back, free, for another.
• Rate limits are shared: one active client can slow the others.
• Run slots are shared: your organization executes at most 5 runs at the same time by default, for all your clients together. One client’s batch of runs makes the other clients’ runs wait queued. In model A, each client’s organization has its own 5 slots. See Runs per organization.
• GET /v1/runs and GET /v1/workspaces return resources for all your clients. Always filter by workspace_id.

• Keep the key on your server. Your frontend calls your backend, never Retriever directly.
• Prefix Idempotency-Key with the tenant id.
• Log tenant_id + run_id to trace consumption.