Users & teams

This page covers two related things: how a request becomes authorized (a built capability — sign-in, tokens, scoped credentials), and how users, roles, and teams are organized (the account-management layer that sits on top).

The access model is small on purpose: a user signs in once, and that single identity authorizes everything that follows — the Reader’s direct reads and the Integration API. There is no separate API key, no long-lived secret in the client. Authorization is always a fresh, expiring token bound to a provisioned identity.

The chain: sign-in → token → scoped credentials

  1. Sign-in. A user authenticates against a Cognito User Pool. The flow is USER_AUTH — a passkey (WebAuthn / Touch ID) or a password, with no Auth0 and no Amplify on the path. A successful sign-in yields a short-lived ID token plus a refresh token.
  2. Federation. That ID token is exchanged, through a Cognito Identity Pool, for temporary AWS IAM credentials (minutes-to-an-hour lifetime). This is what lets the browser talk to the datastore at all — the client never holds a static cloud key.
  3. Access. The credentials (or the ID token, for the API) authorize reads. When they expire, the refresh token mints a new set silently; when that expires, the user signs in again.

The same ID token serves both access models below — one login, two doors.

Two access models

Adjudicate reads its data two ways, for two consumers:

  • Client-direct. The Reader holds the federated IAM credentials and talks to the datastore and object store directly — no application server in the request path. The credential is the authorization; there is no server tier to compromise, and a credential can only reach the appeal it was scoped to.
  • Integration API. Other systems present the ID token to an API Gateway JWT authorizer, which validates it before any handler runs. This is the contract for intake systems, drafting tools, and partners (Integration API).

Both start from the same sign-in. The difference is only what carries the authorization downstream: temporary IAM credentials for the Reader, a JWT for the API.

Identity vs. access

Sign-in is the entry boundary — it establishes who is asking. Which records that identity may reach is decided separately, at the data path (see Data & isolation).

  • Authentication answers “is this a provisioned identity, and is the token valid?” — the Cognito gate and the API authorizer.
  • Isolation answers “which records can this request reach?” — the per-appeal key prefix and the tenant boundary.

A token proves identity; the data path independently governs what that identity returns. The isolation boundary holds the same way regardless of which access model carried the request in.

Why Cognito-only

The direction across the environments we control is Cognito-only — no Auth0, no Amplify, no cloud SDK on the sign-in critical path (the sign-in exchange is a handful of unsigned HTTPS calls, so the heavy SDK loads lazily, after auth). One identity provider issues both the API-gating JWT and the federated IAM credentials; tokens are short-lived and revocable; and the same module backs every environment, differing only by which pool it points at.

Accounts, roles, and teams

Above the identity chain sits the organizational model:

  • Users are provisioned identities in the tenant’s realm. Provisioning, deactivation, and credential reset are tenant-admin operations — there is no self-service signup in an adjudication deployment.
  • Roles gate capabilities (who may decide, who may only review, who administers). Roles are distinct from isolation: a role widens or narrows what actions an identity can take, while isolation governs which appeals it can reach at all.
  • Teams group users for assignment. The workflow engine assigns work to a team or an individual; team membership is what routes a queue item to the right people. An assignee can be a person or a team, and reassignment moves work between them.

Roles and teams are the inputs the workflow engine reads when it decides who a piece of work can be assigned to — so this layer and Workflow work hand in hand.