Multi-tenant setup

When one AI Gateway deployment serves several customers, teams, or products, each tenant’s requests must be tracked and isolated so usage, cost, and traces can be reported per tenant. Orq.ai offers two request-level mechanisms for this:

Identities, which represent a tenant or its end users on each request.
Request metadata, which tags a call with a tenant ID or other key-value data.

This guide covers both approaches, when to use each, and a worked example that routes, budgets, and observes a single tenant end to end. For isolating the data those requests retrieve (for example knowledge bases per tenant), see Isolating data and knowledge bases per tenant.

Which approach to use

Choose the approach by how fixed each tenant is and by what needs to be enforced or reported. Use an Identity for tenants or end users that are known and stable, when cost and usage must be metered, capped, and reported per identity. Use metadata when requests only need a tag to filter on later, and the tenant isn’t something to budget against.

	Identity per tenant	Request metadata
Represents	A known, addressable tenant or end user	Arbitrary key-value context on a request
Carrier	`identity` object or `X-ORQ-IDENTITY-ID` header	`metadata` object or `X-ORQ-METADATA-*` headers
Cost & usage reporting	Grouped and filtered per identity	Not a Reporting dimension; filter traces only
Budgets	Per-identity budget caps	Not a budget scope
Traces & analytics	Filtered by Identity	Filtered by `metadata.<key>`
Best for	Tenant billing, per-tenant budgets, end-user attribution	Tenants that don’t map cleanly to a fixed identity, ad hoc tagging

Approach 1: Identity per tenant

An Identity represents a User, Team, Project, or Client. Create one identity per tenant and attach it to every request that tenant makes. Usage, cost, and traces then attribute to the identity, enabling per-tenant reporting, per-identity budgets, and trace filtering. Create an identity for each tenant once:

curl --location 'https://my.orq.ai/v2/identities' \
--header "Authorization: Bearer $ORQ_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "tenant-acme",
    "display_name": "Acme Corp",
    "metadata": {
      "plan": "enterprise"
    }
}'

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

const identity = await orq.identities.create({
  externalId: "tenant-acme",
  displayName: "Acme Corp",
  metadata: { plan: "enterprise" },
});

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

identity = orq.identities.create(
    external_id="tenant-acme",
    display_name="Acme Corp",
    metadata={"plan": "enterprise"},
)

Then pass the identity on each request, in the body or as a header:

curl -X POST https://my.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Help me resolve a billing issue",
    "name": "SupportAssistant-Production",
    "identity": {
      "id": "tenant-acme"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://my.orq.ai/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Help me resolve a billing issue",
  name: "SupportAssistant-Production",
  identity: { id: "tenant-acme" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://my.orq.ai/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Help me resolve a billing issue",
    extra_body={
        "name": "SupportAssistant-Production",
        "identity": {"id": "tenant-acme"},
    },
)

print(response.output_text)

Identity management uses the Orq SDK (orq.identities.create); requests run through the OpenAI-compatible SDK (openai client) or the /v3/router endpoints, which accept the identity and metadata fields on the request body. To track both a tenant and the person acting for it, give each end user an identity ID such as tenant-{orgId}-{userId}, or create one identity per tenant and share it across that tenant’s users. See Attaching an identity to a request for the body, header, and API-key-owner sources, in the order the gateway checks them.

Approach 2: Request metadata

For tenants that don’t map to a fixed set of identities, tag requests with request metadata. Metadata adds key-value context such as tenant_id, region, or tier, which appears on traces as metadata.<key> span attributes and can be used as a trace filter. Pass a metadata object on the request:

curl -X POST https://my.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize my contracts",
    "metadata": {
      "tenant_id": "acme",
      "region": "eu-west-1"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://my.orq.ai/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Summarize my contracts",
  metadata: { tenant_id: "acme", region: "eu-west-1" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://my.orq.ai/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Summarize my contracts",
    extra_body={"metadata": {"tenant_id": "acme", "region": "eu-west-1"}},
)

print(response.output_text)

When the request body cannot be modified, set the metadata with headers instead. Each X-ORQ-METADATA-<key> header sets one metadata key, lowercased from the header suffix:

cURL

curl -X POST https://my.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-ORQ-METADATA-TENANT_ID: acme" \
  -H "X-ORQ-METADATA-REGION: eu-west-1" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize my contracts"
  }'

Metadata feeds routing rules, guardrail rules, and budget matching, and appears as a trace filter, so requests can be routed, guarded, and inspected per tenant without an identity. Metadata is not a Reporting dimension or a budget scope. To aggregate cost per tenant or cap a tenant’s spend, use the identity or project scope instead.

Keep metadata to a small, fixed set of low-cardinality keys such as tenant_id, region, and tier. High-cardinality values, such as per-request IDs, defeat filtering and increase storage. See Request metadata best practices.

Identity and metadata together

Use an Identity to meter and budget a tenant; use metadata for extra context such as region or product line. The two work together: attach the tenant’s Identity for per-tenant attribution and budgets, then add metadata to describe the request.

Worked example: one tenant, end to end

This example sets up Acme Corp as a tenant with per-tenant routing, a monthly budget, and per-tenant observability, using an identity plus a routing rule keyed on identity and metadata.

Create the tenant identity

curl --location 'https://my.orq.ai/v2/identities' \
--header "Authorization: Bearer $ORQ_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "tenant-acme",
    "display_name": "Acme Corp"
}'

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

const identity = await orq.identities.create({
  externalId: "tenant-acme",
  displayName: "Acme Corp",
});

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

identity = orq.identities.create(
    external_id="tenant-acme",
    display_name="Acme Corp",
)

Cap Acme's spend

Navigate to Settings > Organization > Budgets and click Create. Set Scope > Applies to to Identity, select the tenant-acme identity, and set a monthly Cost limit. When the limit is reached, requests matching Acme’s identity are rejected until the monthly reset, while other tenants keep working. See Budgets for period limits and alerts.

Anyone with a key can set an Identity on a request; the gateway does not check that the key owns that identity. So identity-based budgets and cost reporting are only as trustworthy as the keys that can reach the gateway. Give keys only to trusted backends. To cap spend for untrusted tenants, use a per-tenant key or per-tenant project instead of identity matching.

Route and observe Acme's traffic

On each request, attach the identity and a metadata key so routing and trace filters can target Acme:

curl -X POST https://my.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/support-bot",
    "input": "Reset my password",
    "identity": {
      "id": "tenant-acme"
    },
    "metadata": {
      "tenant_id": "acme"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://my.orq.ai/v3/router",
});

const response = await client.responses.create({
  model: "agent/support-bot",
  input: "Reset my password",
  identity: { id: "tenant-acme" },
  metadata: { tenant_id: "acme" },
});

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://my.orq.ai/v3/router",
)

response = client.responses.create(
    model="agent/support-bot",
    input="Reset my password",
    extra_body={
        "identity": {"id": "tenant-acme"},
        "metadata": {"tenant_id": "acme"},
    },
)

Create a Routing Rule whose condition matches the Identity tenant-acme to send Acme’s traffic to a dedicated model or variant. Combine conditions on identity and metadata (for example region) with the rule builder.

Report Acme's usage and cost

Query the Reporting API, filtering to the tenant identity:

FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "1 day ago" +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -X POST "https://my.orq.ai/v2/reporting" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"metric\": \"genai.usage\",\"from\": \"$FROM\",\"to\": \"$TO\",\"grain\": \"day\",\"group_by\": [\"identity\"],\"filters\": [{\"field\": \"identity\",\"op\": \"eq\",\"values\": [\"tenant-acme\"]}]}"

from orq_ai_sdk import Orq
from datetime import datetime, timedelta, timezone
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.reporting.query(
    metric="genai.usage",
    from_=datetime.now(timezone.utc) - timedelta(days=1),
    to=datetime.now(timezone.utc),
    grain="day",
    group_by=["identity"],
    filters=[{"field": "identity", "op": "eq", "values": ["tenant-acme"]}],
)

In the Traces view, filter by Identity tenant-acme, or by Metadata tenant_id: acme, to inspect Acme’s latency, token usage, and errors.

Isolating data and knowledge bases per tenant

Request-level attribution meters usage, but it does not separate the data a tenant can retrieve. To isolate content, put each tenant in its own Project:

Projects are the isolation boundary. A Project holds Deployments, Prompts, Agents, Knowledge Bases, and Datasets, with project-scoped observability and budgets.
Knowledge bases follow the project. A knowledge base lives under a project/path and is retrieved through a Deployment in that project. With one project per tenant, a tenant’s key cannot reach another tenant’s knowledge base.
Single-project keys stay inside the tenant. Only keys created with single-project scope are confined to that tenant’s project. Workspace-wide and legacy keys can reach every project, so issue single-project keys to tenants and never hand out a workspace-wide key.
Or share one knowledge base among trusted tenants. If tenants trust one another, tag chunks with a client_id metadata field and add a filter_by condition to narrow retrieval to that tenant. This is a query-time filter, not enforced access control: any caller can omit it and read every tenant’s chunks. Use it only among trusted tenants; otherwise separate tenants into per-tenant projects. See Chunk Metadata in Knowledge Bases.

For a full setup: one project per tenant for data isolation and per-tenant budgets, an Identity (or the project-scoped key) so usage reports and traces attribute to the tenant, and metadata for extra context such as region or product line.

Identities

Create identities and attach them to requests for per-tenant attribution and budgets.

Request Metadata

Attach name, identity, thread, tags, and custom metadata to AI Gateway requests.

Budgets

Cap spend per workspace, project, identity, API key, provider, or model.

Reporting API

Query per-tenant usage, cost, and performance programmatically.

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Common Scenarios

Which approach to use

Approach 1: Identity per tenant

Approach 2: Request metadata

Identity and metadata together

Worked example: one tenant, end to end

Isolating data and knowledge bases per tenant

See also

Identities

Request Metadata

Budgets

Reporting API

​Which approach to use

​Approach 1: Identity per tenant

​Approach 2: Request metadata

​Identity and metadata together

​Worked example: one tenant, end to end

​Isolating data and knowledge bases per tenant

​See also

Identities

Request Metadata

Budgets

Reporting API

Which approach to use

Approach 1: Identity per tenant

Approach 2: Request metadata

Identity and metadata together

Worked example: one tenant, end to end

Isolating data and knowledge bases per tenant

See also