RequestContext

Every call into the BetterSuite GraphQL API produces a RequestContext server-side before any resolver runs. This is the canonical view of "who is calling" that every resolver branches on — knowing how it's assembled helps you predict why an operation accepts you, rejects you, or returns less than you expected.

How it's built

The auth middleware sits in front of every GraphQL request. It:

1. Strips every client-set context header (x-account-id, x-tenant-id, x-session-id, x-role, x-partnership-id, x-elevation-jti). A malicious client can't assert another tenant's id; the server fills these in itself.
2. Picks the auth mode in this order: Authorization: Bearer (JWT) > X-Api-Key (btk_* or bpk_*) > unauthenticated.
3. Re-injects the resolved context as internal headers, which the GraphQL handler reads into RequestContext.

So the structure below is server-asserted — by the time your resolver sees it, every field has been derived from a verified token or key.

Fields

pub struct RequestContext {
    pub account_id: Option<AccountId>,
    pub tenant_id: Option<TenantId>,
    pub session_id: Option<SessionId>,
    pub role: Option<RoleKind>,
    pub app: Option<App>,
    pub partnership_id: Option<PartnershipId>,
    pub device: Option<RequestDevice>,
    pub ip: Option<String>,
    pub user_agent: Option<String>,
    pub client_version: Option<String>,
    pub elevation_jti: Option<String>,
    pub anonymous_session_id: Option<uuid::Uuid>,
}

Every field is Option. Resolvers grab what they need via accessors like req_ctx.tenant_id() (returns an error if missing). What gets populated depends on which auth path matched.

Auth-derived fields

app is the one client-asserted field the middleware does not strip on a pre-auth request — pre-auth flows (e.g. loginWithPassword from a specific app) need to know which app sent the call. JWT-authenticated requests still get their app overwritten from the access-token claims, so post-auth resolvers always see the authoritative value.

Context fields

Tenant resolution — the only mechanism

There is no host-based tenant resolution and no client-supplied X-Tenant-Id header. Tenant id comes from exactly one of:

1. The tid claim in a JWT access token.
2. The tenant_id row of the API key (btk_*) that authenticated the call.
3. The tenant matched by the public client key (bpk_*) on a pre-auth call.

Any inbound x-tenant-id header is stripped before the middleware does anything else, so cross-tenant assertion isn't possible from the client side. Calls without one of the three above arrive at tenant_id = None; resolvers that need a tenant return an error.

Roles

RoleKind (snake_case on the wire):

The is_owner_tier() accessor returns true for tenant_owner and platform_admin; the is_admin_tier() accessor adds tenant_admin to that. Resolvers use these instead of open-coded match arms.

Step-up elevation

elevation_jti is set only after the auth middleware validates a X-Elevation JWT (signature, audience "step-up", tenant + subject must match the bearer JWT). Setting it does not consume it — the gated resolver calls require_elevation(elevation_jti, store), which atomically deletes the JTI from Redis. Single-shot semantics: one successful mutation per token.

If the header is missing, the JWT is malformed, the audience is wrong, the tenant/subject mismatches the bearer, or Redis is unavailable, the resolver returns STEP_UP_REQUIRED.

Error codes

These come back as GraphQL errors (errors[].extensions.code), not HTTP status codes — the HTTP response stays 200 once parsing succeeds. Identity-service codes you'll commonly encounter:

HTTP-level 401s are reserved for the auth middleware itself (bad JWT signature, unknown / revoked / malformed API key).

What's next

• API Keys — populates tenant_id only.
• JWT Sessions — populates account_id, session_id, role, app, and (for partner staff) partnership_id.
• Rate Limits — bucketed differently by auth kind.