Teams & multi-tenancy

Teams are how Stream Trace scopes access. Streams are owned by one or more teams, and users get access to a stream by holding a team-scoped role on a team that owns it. A user only ever sees the streams their teams own (except instance_admin, which sees everything).

Provisioning teams

Create teams at startup, or let an access admin create them in the UI:

ST_AUTH_PROVISIONED_TEAMS_JSON='[
  {"slug":"payments","display_name":"Payments"}
]'

Stream ownership

Ownership maps a stream to the team(s) that can access it. It is resolved in this order:

1. Admin UI override - set per stream from the admin console.
2. Provisioned config - ST_AUTH_STREAM_OWNERSHIP_JSON.
3. NATS stream metadata fallback - streamtrace.teams with comma-separated Stream Trace team slugs.

ST_AUTH_STREAM_OWNERSHIP_JSON='[
  {"stream_name":"ORDERS","team_slugs":["payments"]}
]'

Optional metadata fallback:

nats stream edit ORDERS \
  --metadata='streamtrace.teams=payments,platform' \
  --force

Stream Trace reads this metadata but does not edit it. The named teams must already exist.

A stream with no owner is not accessible to non-admin users until ownership is assigned.

Mapping OIDC groups to roles

Grant access automatically based on identity-provider groups. Teams referenced by a mapping must already exist (via provisioned teams or created by an access admin):

ST_AUTH_PROVISIONED_ROLE_MAPPINGS_JSON='[
  {
    "provider_id":"okta",
    "group":"streamtrace-payments-admins",
    "global_roles":[],
    "team_roles":[{"team_slug":"payments","role_slug":"stream_admin"}]
  }
]'

When a user signs in through OIDC, their groups are matched against these mappings to assign global and team roles.

How multi-tenancy works in practice

• Give each team a stream_admin or stream_viewer role on the streams it owns.
• Assign streams to the owning team via config or the admin UI.
• Users see only their teams’ streams, DLQ cases, and traces - everything else is filtered out by the API, not just hidden in the UI.

See Roles & permissions for the full permission set and Administration for managing it all from the console.