Tenancy and end-user attribution

Every authenticated request runs in one credential-derived Tenant context. Within that boundary, optional Attribution labels activity with an opaque end-user userId and metadata so a backend can filter resources and report usage.

Tenant isolation

A backend API key establishes the trusted Tenant context. Services use that credential-derived tenantId for reads and writes, so a request cannot select another Tenant by supplying userId, metadata, or a resource ID. See REST authentication for all accepted credential paths.

One API key has Tenant-wide authority. The tenant's backend must authenticate its end-user, authorize the operation, select allowed Agent and resource IDs, and only then call Blazing Agents.

Attribution fields and propagation

Attributed create inputs accept userId and metadata. Both default to the tenant-level values userId: "" and metadata: {}. The userId convention is immutable after creation; resource update contracts may allow metadata changes without allowing the Attribution identity to move.

Agents, Sandboxes, tenant Skills, Prompts, Sessions, Tasks, Task runs, Artifacts, Memories, and usage records carry Attribution. Tenant configuration such as API keys, Providers, and quota settings does not.

For a new Session, its first successful Turn stamps the Turn's userId and metadata on the lazily materialized Session. The same values enter that Turn's usage record. A Task run inherits Attribution from its Task, and the run's fresh Session, usage, and any Artifacts saved by its Agent use those values. An Artifact deliberately saved during an interactive Turn uses the Turn's Session ownership and Attribution.

Attribute a Turn and filter results

Derive the identifier from authenticated backend state, then reuse it as a filter:

import { BlazingAgents } from "@blazing-agents/sdk";

const apiKey = process.env.BLAZING_AGENTS_API_KEY;
if (!apiKey) throw new Error("BLAZING_AGENTS_API_KEY is required");

const client = new BlazingAgents({ apiKey });
const agentId = "ag_0123456789abcdef";
const userId = "usr_7f3a9c";

const turn = await client.chat({
  agentId,
  message: { id: "msg_user_1", role: "user", parts: [{ type: "text", text: "Summarize my open items." }] },
  userId,
  metadata: { workspace: "primary" },
});

for await (const _chunk of turn.toUIMessageStream()) {
  // Drain the Turn so a successful transcript can commit.
}

const sessionId = await turn.sessionId;
const sessions = await client.sessions.list(agentId, { userId });
console.log(sessions.data.some((session) => session.id === sessionId));

After the Turn succeeds, the final expression prints true because the filtered Session list includes the materialized Session.

Reporting and filtering

Session lists accept a userId filter. Tenant-wide and per-Agent usage queries can filter by userId or group by user; usage also supports Agent, model, Session, day, and time-window dimensions. See sessions.list and usage.get for exact fields.

Omitting a userId filter includes all Attribution buckets visible to the Tenant credential. Passing userId: "" selects only tenant-level activity; a non-empty value selects that exact opaque identifier.

What Attribution is not

Attribution is not authentication. It is not authorization. It is not an ACL, and it is not a stored end-user account. Supplying a userId neither proves identity nor narrows what an API key can access.

Production considerations

Derive a stable, opaque userId on the backend. Keep the mapping to a real identity in the tenant's own system.
Treat metadata as product data: minimize personal information, validate values at the backend boundary, and apply the tenant's retention policy.
Check application ownership before reading, resuming, updating, or deleting a resource. A matching Attribution filter is not an authorization check.
Decide whether missing Attribution should mean tenant-level activity. Because omission defaults to userId: "", accidental omission otherwise merges activity into that bucket.

See Security and credentials, Usage and quotas, Sessions and Turns, and Artifacts for the corresponding execution and storage boundaries.

Build a multi-tenant application