Identity, organizations & access

Start with the organisation as the scope root

Enable the organisations capability in the application configuration, then declare which business resources belong to that scope. The organisation record supplies identity and lifecycle; the relationship graph carries ownership into child resources. A tenant field alone is not a substitute for declaring the resource’s scope.

In wildo.saas.config.ts, keep the application’s other capabilities and enable this entry in engineCapabilities:

[EngineCapability.ORGANIZATIONS]: { enabled: true },

EngineCapability is exported by @wildo-ai/saas-models. This enables the organization mechanisms; it does not make every business record tenant-owned. Declare the primary ownership relationship for each relevant resource. This selected Wonder Todos declaration connects todos to their organization:

createResourcesRelationship(
  CoreResourceType.ORGANIZATIONS, TasksManager_ResourceType.TODOS,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'organizationId',
    contextPolicy: {},
  },
)

The relationship factory and framework enums come from @wildo-ai/saas-models; TasksManager_ResourceType belongs to the example application. Its todo schema declares organizationId as a foreign key. The module contributes moduleResourcesRelationships through SharedSaaSModule.resourceRelationships, alongside its resource configuration factories and field identifiers, and the existing shared-module registry aggregates them. The resource factory derives organization scope from the primary relationship; do not maintain a second resourcePrimaryScope setting.

To verify the connection, use the authorized organization-contextual todo operations: records created for one customer should be available in that workspace, and an unrelated customer must not be able to address them. The caller’s actual membership and the operation’s roles still govern admission. The organization-scope guide follows the same declaration into query confinement.

Keep the workspace URL identity stable

The following is the actual slug declaration from organizations.shared.schemas.ts. It separates the stable URL identity from an editable display name:

slug: z.string()
  .min(1)
  .max(50)
  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
  .isDBIndexed()
  .isUnique({ conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_SLUG_EXISTS })
  .isSummaryField()
  .excludeFromUpdate(),

Keep identity, membership and lifecycle separate

A person’s organisation roles live on their membership, not on the organisation or a global account-role list. The organisation’s type selects configured policy. Its status is controlled by lifecycle operations rather than a generic update.

A self-service create also creates the requester’s owner membership. An operator-created organisation follows a separate creation path; do not assume every create variant appoints the caller as its owner.

Use organisation types for provisioning choices and organisation membership for a person’s authority inside the workspace. Database uniqueness must be present in the deployed database: the schema’s index declaration and an applied SQL migration are distinct steps.

Declare the type and its creation policy together

The example below illustrates an organisation-type entry in organizationTypes. business-user is an application-owned user-type key: define that user type before referring to it here.

customer: {
  userTypes: ['business-user'],
  availableOrgRoles: [
    CORE_ORG_ROLES.ORG_OWNER,
    CORE_ORG_ROLES.ORG_ADMIN,
    CORE_ORG_ROLES.ORG_MEMBER,
  ],
  defaultMemberRole: CORE_ORG_ROLES.ORG_MEMBER,
  creationPolicy: {
    createOnUserTypeRegistration: ['business-user'],
    orgNameSource: OrganizationNameSource.ASK,
    defaultOwnerRole: CORE_ORG_ROLES.ORG_OWNER,
  },
},

Import the named role and name-source values from @wildo-ai/saas-models. userTypes describes the application user types membership grants; availableOrgRoles and defaultMemberRole describe authority inside this organisation. They are different dimensions.

Follow the creation path

When the configured user type registers, the registration flow creates the organisation through its internal create variant and establishes the owner membership. ASK, AUTO and ONBOARDING select how its name is obtained. A registering user type may match at most one organisation type; ambiguous matches are configuration errors.

The create prefix validates the type and rejects a policy-managed type outside the registration-managed path. Omitting creationPolicy leaves that type outside automatic registration creation; it does not itself grant permission to create it.

Make membership-dependent user types explicit

The two directions are configured separately. organizationTypes.customer.userTypes grants business-user when a person joins. To make that user type depend on continued membership, add requiresOrgMembership to the corresponding entry in the application’s userTypes map:

import type { UserTypeDefinition } from '@wildo-ai/saas-models';

// existingBusinessUserType is your complete, already configured user type.
const membershipBoundBusinessUser: UserTypeDefinition = {
  ...existingBusinessUserType,
  requiresOrgMembership: {
    orgTypes: ['customer'],
  },
};

Use membershipBoundBusinessUser as userTypes['business-user'] in the existing authored backend configuration, alongside organizationTypes.customer above. Keep the existing full auth policy, application roles and frontend usersManagement entry. This excerpt adds the membership condition; it does not replace the application’s identity or authentication setup.

A remaining membership qualifies only when it is active and its organization still confers authority. Losing a type can invalidate sessions; a membership change that removes no type does not imply that every session is terminated. Organization roles still govern access inside each workspace independently of this application-level type lifecycle.

Choose how organisation authentication may vary

A type can also carry authOverrides. Method changes follow the application’s orgAuthMethodPolicy: RESTRICT_ONLY removes methods, EXPAND_WITHIN_SET permits additions from expandableOrgMethods, and UNRESTRICTED accepts the override method set. Do not assume every application uses the restrictive default.

MFA, password and step-up settings have their own merge rules. Review the resolved policy, not just the type’s override block. Creation policy, access roles and authentication policy remain separate decisions.

Treat the membership as its own record

organizationMembers joins an organisation and a user. That pair is the membership’s business identity; roles and status describe what the connection currently permits. Directory information can change without changing the linked account.

Address the membership, not the account

An organization administrator updates an existing membership at the route below. MEMBERSHIP_ID is the membership record’s _id, not the global user ID; ORG_ID is the workspace that owns it. This example keeps ordinary membership and adds the manager role:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/organization-members/$MEMBERSHIP_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"roles":["ORG_MEMBER","ORG_MANAGER"]}'

Use roles available to that organization type and within the caller’s grant ceiling. The submitted array is the resulting role set, not an instruction to append one role. Read the membership back to check the persisted roles, then exercise the operation those roles are intended to permit. Preserve any existing responsibilities the person should retain; removing the last usable owner is refused.

The ordinary update cannot change userId or status. Accepting an invitation, suspending a member and reactivating a member each have their own guarded transition. Setting status: "ACTIVE" in this payload is not an acceptance flow.

Understand when a role takes effect

An invited membership does not confer the privileges of an active member. Acceptance activates the membership and is where organisation-granted application user types become effective. The organization-type configuration declares both the types granted on joining and the membership requirement used to revoke them later. Role edits check the caller’s grant ceiling, including roles that will only become active after invitation acceptance.

Remove access through the right action

A pending invitation is revoked through its invitation operation. An established member is removed with DELETE /organizations/{organizationId}/organization-members/{membershipId} using an authorized organization administrator. This removes their membership in that workspace, not their global account. The implementations distinguish these states, remove dependent unit assignments where applicable and reconcile application-level user types that came from the organisation.

The owner floor protects changes that would retire the last usable owner. A role array is therefore not merely editable metadata: its update participates in authority and continuity checks. Use unit roles when a person’s responsibility applies to one department rather than the whole organisation.

Update the profile, not the tenant’s lifecycle record

The profile is a resource associated with the organisation. This illustrative profile payload shows company information alongside the branding values used by sign-in presentation:

{
  "displayName": "North Studio",
  "website": "https://north.example",
  "branding": {
    "logo": "https://north.example/logo.png",
    "primaryColor": "#234C72"
  }
}

Submit the fields through the organisation profile’s generated update operation, with authority over that organisation. The logo is an absolute URL. A profile edit does not verify ownership of a sign-in domain or change how users authenticate.

Follow branding to its consumer

authentication-orchestrator.backend.service.ts loads branding for the organisation resolved during identification. resolveTenantBrandPresentation resolves fields independently. The caller supplies the application logo as fallback; it supplies no application primary colour for this DTO, so an unset tenant colour remains absent.

The standard AuthPage_Main passes auth.identification?.organizationBranding to its public layout. usePublicShellLayout applies that input only for the login card layout, when no explicit shell identity overrides it. The header must be enabled with publicShellIdentityMode: PublicShellIdentityMode.BRAND_HEADER in the frontend configuration; an absent header is not enabled merely because a profile has a logo.

Reuse the presentation contract in a custom login layout

A custom public-layout implementation can obtain the same resolved identity through the exported hooks:

import { useAuthSession, usePublicShellLayout } from '@wildo-ai/saas-frontend-lib';

export function useIdentifiedLoginLayout() {
  const { auth } = useAuthSession();
  return usePublicShellLayout(
    true,
    auth.identification?.organizationBranding,
  );
}

This illustrative hook belongs in a custom login layout beneath the normal application, UI and authentication providers. Render the returned brandHeader only when it is present. It supplies the resolved name and optional logo; brandAccentColor supplies the optional decorative tenant colour. Keep the existing label beside an unclassified logo and use the application’s design-system colour handling rather than treating an arbitrary profile colour as a text-contrast policy.

A verified organization domain can supply login branding even when SSO is disabled. The name comes from the organization record; the logo and colour come from its profile. This presentation lookup does not select sign-in methods, grant membership or change access rules. Pass identification branding only to the intended login layout; registration and legal pages should not inherit the last login attempt’s tenant.

That is the supported presentation contract here. The stored favicon, secondaryColor and customDomain fields do not imply corresponding sign-in DTO fields or automatic domain provisioning. Business-profile content is available through the resource pipeline; custom screens can choose how to present it.

Keep domain verification in the authentication configuration. A business website or profile domain describes the organisation; it is not proof that the organisation controls that domain.

Distinguish language policy from regional defaults

An illustrative organisation-preferences update is:

{
  "timezone": "Europe/Paris",
  "locale": "en",
  "dateFormat": "LOCALE_DEFAULT",
  "timeFormat": "24h",
  "languagePreferences": {
    "primaryLanguage": "en",
    "supportedLanguages": ["en"],
    "allowUserOverride": true,
    "enforceForAllMembers": false
  }
}

Use your generated schema’s actual DateFormat, TimeFormat and AvailableLanguage values when constructing this payload; the named values above describe the intended choices. The resource is seeded with defaults when the organisation is created and edited through its organisation-scoped update operation.

Follow the active organisation into the interface

UserOrgsContext publishes the active organisation’s language and regional preferences. I18nContext stores them separately from the member’s preferences. resolveRegionalFormatting resolves each regional field from member choice, then organisation default, then the framework fallback.

Language resolution additionally respects the application’s organisation-override policy and the tenant’s supported languages. enforceForAllMembers or disabling allowUserOverride can require the tenant’s language; these switches do not turn its regional settings into forced personal values.

Check both inheritance and an explicit choice

Verify a member with no regional values first, then one with an explicit timezone or format. A third useful check switches organisations: defaults should follow the new organisation while the member’s deliberate override remains theirs.

Configure addresses and category switches together

This illustrative emailNotifications value routes two categories and leaves the others enabled with a default address:

{
  "emailNotifications": {
    "defaultEmailAddress": "operations@example.com",
    "billingAddress": "finance@example.com",
    "securityAddress": "security@example.com",
    "billing": true,
    "security": true,
    "administrative": true,
    "usersManagement": true
  }
}

The organisation notification resource is seeded during organisation creation. Update its settings through the generated organisation-scoped resource operation; no custom dispatcher is needed for these standard categories.

Routing still needs a registered email template and a configured delivery provider. Follow the template registration example and transactional email setup for those prerequisites. Saving a destination address does not supply either one or prove message delivery.

Understand delivery precedence

For an email with a mapped organisation target, the dispatcher checks the category switch first. false suppresses the category, including ordinary member fan-out. Otherwise it uses the category address, then defaultEmailAddress, then the existing member-target resolution when neither address is set.

ORGANIZATION_USERS intentionally remains member fan-out. These settings route email; they do not redirect every channel or every notification target.

Keep fallback behavior visible to operators

A missing settings record or a failed settings read falls back to member delivery. It does not silently drop the message. If a customer requires all mail to remain in a shared inbox, monitor failed settings reads as part of operating that requirement.

The category is derived from the notification target. Declaring another category flag on each notification would create a second answer that could disagree with the routing policy.

Create a node with a deliberate inheritance policy

This illustrative unit-create payload defines a department under an existing parent. The route supplies the organisation context, and parentUnitId names a unit in that organisation:

{
  "name": "European Sales",
  "code": "EU-SALES",
  "parentUnitId": "existing-sales-unit-id",
  "inheritanceType": "inherit_down"
}

Replace the example ID with a real parent. inherit_down lets a role held at this unit reach its descendants; no_inheritance limits it to the assigned unit. There is no upward permission inheritance.

Move through the operation that owns the tree

parentUnitId is excluded from generic updates. Moving a node changes its descendants’ materialised paths too, so use the unit’s move operation. The node’s path is server-owned, not something the client calculates and patches.

A unit’s optional code is unique among siblings. The parent is part of that identity: two departments may use the same code under different parents without representing the same node.

Invoke moves and lifecycle transitions on the addressed unit

For an organization administrator, moving a unit uses this request. UNIT_ID and NEW_PARENT_ID must identify units in the addressed organization:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/organization-units/$UNIT_ID/move" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"newParentUnitId\":\"$NEW_PARENT_ID\",\"reason\":\"Align the regional sales structure\"}"

The move payload names newParentUnitId, not the stored parentUnitId. Send {} to promote the unit to a root; an empty ID is not the root command. The server validates the destination and updates the moved subtree’s paths. Re-read the unit and its descendants to confirm the new hierarchy.

Archiving requires a nonempty reason of at most 500 characters:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/organization-units/$UNIT_ID/archive" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"The regional team has been reorganized"}'

To restore the unit, use PUT on the same route with /restore and send {} or an optional reason of at most 500 characters. Archiving changes that node rather than rewriting every descendant. Restoring a child requires its ancestor chain to be active, so restore archived parents first. These actions change unit availability; they do not move the customer to another tenant or replace membership assignments.

Connect structure to authority explicitly

A tree does not automatically filter all business records. Add unit assignments and opt the relevant resources into unit-based access. Review broad grants at root units carefully: downward inheritance from the root can reach the whole chart even though its source is one unit assignment.

Create an assignment between a membership and a unit

This illustrative unit-member payload names an existing organisation membership and a unit in the same organisation:

{
  "organizationMemberId": "existing-membership-id",
  "organizationUnitId": "existing-sales-unit-id",
  "role": "ORG_MANAGER"
}

The generated operation supplies organisation context. Use the membership ID, not the global user ID. The assignment’s identity is the membership/unit pair; changing its role updates that assignment, while assigning another unit creates a different one.

Address the assignment and keep grant authority separate

Use an organization administrator’s authenticated token to create the assignment:

curl "$BACKEND_URL/organizations/$ORG_ID/organization-unit-members" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"organizationMemberId\":\"$MEMBERSHIP_ID\",\"organizationUnitId\":\"$UNIT_ID\",\"role\":\"ORG_MANAGER\"}"

The built-in CREATE, UPDATE and DELETE operations require ORG_ADMIN, with the role ceiling additionally checking what the caller may grant. Holding a manager role in one unit does not create a self-service right to grant more roles.

Keep the created assignment’s _id for later changes. Update its role through the addressed assignment’s UPDATE operation; remove it through DELETE. organizationMemberId and organizationUnitId are excluded from updates. Moving the person to another unit means creating the new assignment and deliberately retiring the old one, not changing that immutable pair.

Verify the resulting assignment and then call a business resource configured for team-based access. The assignment alone does not filter every resource or remove a broader organization-wide grant.

Follow the role into an access decision

The execution context carries the role with its organizationUnitId. On an opted-in resource, the authorisation decision checks which assignments actually satisfy the operation’s required roles. It does not include every unit the member happens to belong to.

Downward inheritance can extend reach to descendants according to the unit policy. The context distinguishes directly held and inherited units so the resulting scope remains explainable.

Do not accidentally grant organisation-wide access

The grant ceiling applies to both create and update. Unit roles do not replace an already sufficient organisation-wide role; if that broader role permits the operation, unit narrowing does not subtract its access. Choose organisation roles and unit assignments together, then test with a member whose only qualifying role is the unit assignment.

Give the resource a real unit field

Wonder Todos’ TeamGoals_Schema contains both the customer and team identifiers. These selected fields are from shared-lib/src/modules/tasks-manager/resources/team-goals/team-goals.schemas.ts, after initZodDecorators(z) initializes the decorators:

organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
organizationUnitId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField(),

These are fields inside z.object, not a standalone schema. The organization relationship establishes tenant ownership; organizationUnitId identifies the team within it. The required field prevents unit-less goals. It remains editable so an organization-wide manager can move a goal, while a confined manager cannot move it outside their permitted units.

Require a role that the team grant can supply

The resource’s operationsConfiguration requires CORE_ORG_ROLES.ORG_MANAGER. Here is its READ entry; Wonder Todos makes the same role choice for LIST, CREATE, UPDATE and DELETE:

[CoreResourceOperation.READ]: {
  variants: [{
    variantType: ResourceOperationVariantType.API_CALL,
    isDefault: true,
    roles: [CORE_ORG_ROLES.ORG_MANAGER],
    riskLevel: ResourceOperationRiskLevel.LOW,
  }],
},

The operation enums and CORE_ORG_ROLES are exported by @wildo-ai/saas-models. This entry belongs in the resource configuration passed to createResourceConfiguration_Initialization, alongside mainSchema: TeamGoals_Schema, its resource identifiers, relationships and declared core operations.

The role choice is decisive. With ORG_MEMBER on an operation, an ordinary member already qualifies organization-wide; adding a team grant would not confine that access. With ORG_MANAGER, a person who is only an organization member can qualify through their manager role in Sales, while an organization-wide manager retains broader access.

Register the resource and its narrowing policy

Wonder Todos opts its team-goals resource into narrowing in backend-api/src/bootstrap-config.ts:

const APPLICATION_ORGANIZATION_UNIT_NARROWING: Readonly<Partial<Record<string, { unitFieldName: string }>>> = {
  [TasksManager_ResourceType.TEAM_GOALS]: { unitFieldName: 'organizationUnitId' },
};

const initializationConfig = buildApplicationInitializationConfig({
  additionalServiceImplementations: userSelfCustomImplementations,
  organizationUnitNarrowing: APPLICATION_ORGANIZATION_UNIT_NARROWING,
});

This excerpt keeps the narrowing registration and omits unrelated bootstrap options. The resource factory is separately registered in the task module’s moduleResourcesConfigurationsFactoryMap:

[TasksManager_ResourceType.TEAM_GOALS]: teamGoals_ResourceConfiguration_InitializationFactory,

That is an entry in the existing module map, not a replacement for it. Keep the task module and its relationship declarations in the application’s shared module registration, and pass the backend initialization configuration through the existing startup path. Registering the narrowing field alone does not publish a resource or its routes.

Startup rejects forbidden authorization resources and empty field names. This validator does not receive the resource schema and does not check that the named field exists: matching unitFieldName to a real field remains an authoring obligation. The declaration is backend policy, not a request parameter a caller may use to choose authority.

Assign a team role and call the resource

This request sequence follows Wonder Todos’ organization-unit-narrowing.e2e.ts. Start with two sibling root units, Sales and Legal, and one goal in each. MEMBERSHIP_ID is the person’s existing organization-membership row ID, not their user ID. ADMIN_TOKEN belongs to an organization administrator allowed to assign the role; MEMBER_TOKEN belongs to a person holding only ORG_MEMBER organization-wide.

curl "$BACKEND_URL/organizations/$ORG_ID/organization-unit-members" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"organizationUnitId\":\"$SALES_UNIT_ID\",\"organizationMemberId\":\"$MEMBERSHIP_ID\",\"role\":\"ORG_MANAGER\"}"

curl "$BACKEND_URL/organizations/$ORG_ID/team-goals" \
  -H "Authorization: Bearer $MEMBER_TOKEN"

The first request grants the Sales unit role; it does not promote the person’s organization membership. The second lists goals using that person’s own authority. In this setup, the list includes Sales goals and excludes Legal goals. First confirm that an organization-wide administrator can reach the same registered collection: a missing route is not evidence of confinement.

Apply the same answer at the gate and the records

resolveOrganizationUnitNarrowingDecision first checks whether an organisation-wide grant satisfies the operation. Otherwise it selects qualifying unit grants and returns the unit IDs that may be used by the row filter and write validation.

Test the boundaries, not only the list

Check a list, an addressed read and a write naming another unit. Also check a member assigned different roles in two units: only the unit whose role satisfies the operation should qualify. Context stamps can tighten when combined, not overwrite a narrower decision with a wider one later in the same request.

Use the shell’s organisation switcher

Place the organisation switcher in the application user menu. Its behavior commits the new organisation through the scope context; custom controls should use that same path rather than only changing a stored ID.

The central commit in AppScopeContext.tsx is:

const commitOrganizationScopeValue = useCallback((organizationId: string | null) => {
  setCurrentOrganizationId(previousOrganizationId => {
    if (previousOrganizationId === organizationId) {
      return previousOrganizationId;
    }

    tokenStorage.setOrganizationId(organizationId);

    if (previousOrganizationId && organizationId) {
      notifyOrganizationSwitch(organizationId, previousOrganizationId);
    }

    return organizationId;
  });
}, [notifyOrganizationSwitch, tokenStorage]);

Use the public switch operation in custom controls

A custom React control can use the public hook instead of reproducing the internal scope commit:

import { useUserOrgs } from '@wildo-ai/saas-frontend-lib';

export function useWorkspaceSelection() {
  const { setCurrentOrganization } = useUserOrgs();
  return (organizationId: string) => {
    setCurrentOrganization(organizationId);
  };
}

This illustrative hook belongs beneath the application’s normal providers, including UserOrgsProvider. Connect its returned callback to the existing organization picker and pass an ID from that user’s loaded organization list. The setter checks that list, ignores an unknown ID and does nothing when the selected organization is already active. It returns no new membership or server authorization; the backend still checks each request.

Follow the consumers of that change

AuthSessionContext re-points WebSocket organisation subscriptions. NavigationContext handles PRIMARY_SCOPE_CHANGED inside a navigation transaction and clears old stacks before going home. WebSocketContext independently releases room claims for the previous organisation.

The read cache has a separate owner. In the standard ApplicationMainContext composition, ResourceReadCacheBridge mounts inside AppScopeProvider. An organization change clears cached reads and releases its coverage claims; subsequent reads establish coverage for the new scope. Pending room replies are checked against the current request so a late reply cannot restore retired coverage or remove a newer claim.

Initial organisation establishment is treated differently from switching between established organisations. A refresh that restores the existing organisation must preserve a legitimate deep link rather than send the person home.

Verify with two real memberships

Use one account with access to two organisations containing different records. Open a record, switch, then inspect navigation, list results and live updates. A same-organisation no-op and a hard refresh of a deep link are separate checks; neither proves a genuine organisation-to-organisation transition.

Declare the scope field at the module’s shell boundary

Wonder Todos declares this selector in app-shell.module.frontend.ts:

export const moduleQuickSwitcherFields: QuickSwitcherScopeField[] = [
  {
    resourceType: TasksManager_ResourceType.TODO_LISTS,
    fieldIdentifier: 'todoListId',
    position: 0,
    persist: true,
    optionDisplayMode: ForeignKeyDisplayMode.SUMMARY,
    presentation: QuickSwitcherFieldPresentation.ICON_LED,
  },
];

The module contributes quickSwitcherFields through ShellModuleContributions. resourceType selects the records offered; fieldIdentifier is the value the scope carries. The resource and scope-aware routes must already exist.

The shell must also enable ApplicationLevelComponentType.QUICK_SWITCHER and host that component in its menubar or sidebar. Follow the complete shell hosting example for the module aggregation and both shell configuration entries. An existing host can be reused; declaring fields alone does not put a selector on screen.

Separate the option from the closed control

SUMMARY shows the resource’s summary content in each option. ICON_LED controls how the closed selector sits in the shell; it does not change the option’s record representation. position orders controls and persist retains the selection.

Let routes and selection agree

AppScopeContext turns scope values into route identifiers and request parameters. A record surface can establish its selected record; a collection surface can clear the corresponding selection. Configure one selector per resource scope rather than duplicating competing controls.

The selector does not grant membership or create a security filter. Resource scope and authorisation remain necessary even when the control only offers records the user can see.

Declare the policy where the user type is defined

saas-config.backend.ts owns application-authored identity behavior. In Wonder Todos, these are selected settings from the admin.auth object:

passwordPolicy: {
  minLength: 12,
  maxLength: 128,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSpecialChars: true,
  expiryDays: 90,
},
sessionDurationMinutes: 30,
maxConcurrentSessions: 3,
lockoutPolicy: {
  maxLoginAttempts: 3,
  lockoutDurationMinutes: 60,
  progressiveLockout: true,
  maxProgressiveLockoutHours: 24,
},

Password length, composition and expiry govern the credential. lockoutPolicy governs failed attempts. sessionDurationMinutes limits the temporary authentication episode in which sign-in steps are completed; it does not set the issued access token’s expiry. Registration and invitation episodes are created with a 24-hour expiry; idle timeout and subsequent session-store updates also affect how long they remain usable. maxConcurrentSessions limits authenticated sessions. JWT signing keys and access/refresh token lifetimes belong to deployment runtime configuration.

Make the user type available on the frontend

Enabling AuthMethod.PASSWORD is necessary, but the frontend must also admit the type. Wonder Todos declares:

frontendServices: {
  'wonder-todos-app': {
    usersManagement: {
      member: { register: true, auth: true, isDefault: true },
      admin: { register: false, auth: true },
    },
  },
},

An administrator can authenticate on this frontend but cannot register there. registration.allowedMethods separately controls account creation; the enabled sign-in set is not a signup policy.

Let the authentication flow finish

The standard interface identifies the account’s applicable methods and continues authentication. Password verification alone is not necessarily the final result: required email verification, MFA and account status still matter before a usable session is issued. Custom clients should follow the returned authentication state rather than assume that a successful first factor means access has been granted.

Configure the application identity first

Enable AuthMethod.PASSKEY for the relevant user type and configure the passkey relying party and operational settings. Expected origins come from configured runtime public URLs. These values must match the deployed frontend; enabling the flag alone does not make a credential valid for an arbitrary hostname.

Enrollment proves the application’s challenge

The standard interface requests registration options, invokes the browser authenticator and submits its response. The backend consumes the stored registration challenge and verifies it against the relying party and expected origin. This is the verification call in webauthn.backend.service.ts:

const verification = await verifyRegistrationResponse({
  response,
  expectedChallenge,
  expectedOrigin: this.expectedOrigins,
  expectedRPID: this.rpId,
  requireUserVerification: this.passkeyOps.userVerification === 'required',
});

Successful verification stores the credential’s public key, identifier and authenticator metadata. The secret stays with the authenticator. Public signup still requires email proof before passkey enrollment; an authenticator is not proof of an inbox address.

Authentication has its own ceremony

A later sign-in creates a fresh authentication challenge. The backend consumes it once, verifies the assertion and updates the credential’s counter and last-used information. Synced passkeys with a zero counter are supported; a verified assertion whose nonzero counter regresses is refused and recorded as suspicious.

Sensitive-action reauthentication uses a separate passkey challenge and requires user verification. That distinction prevents a login response from being reused for a high-impact action. Enrollment, naming and removal are separate account operations; removing a credential remains subject to account method-management policy.

Enable sign-in and arrange delivery

Wonder Todos enables [AuthMethod.MAGIC_LINK]: true in the member’s authMethodsEnabled. Email delivery and the frontend public URL must also be configured. Passwordless public signup is a separate choice in registration.allowedMethods.

The controller builds the link from the selected frontend and passes it to the transactional email service. Verification checks the declared frontend’s origin, then checks whether the resolved account type may authenticate on that frontend before creating a completed or MFA session. The frontend’s default type is a routing hint; it does not grant a type the account does not hold.

Preserve the authentication continuation

After the link is consumed and its policy checked, the orchestrator evaluates MFA using the effective policy:

await this.updateSession(sessionId, {
  state: AuthenticationSessionState.MFA_REQUIRED,
  requiresMFA: true,
  availableEnrollmentMethods: availableEnrollment,
  requireStrongMFA: mfaResolution.requireStrongMFA,
  availableSecondFactorMethods: mfaResolution.availableMethods,
  enrolledSecondFactorMethods: mfaCheck.enrolledMethods,
  usableSecondFactorMethods: mfaResolution.usableMethods,
});

The standard Auth_MagicLinkVerify screen follows the returned state. A custom screen must do the same: do not treat successful link verification as permission to skip MFA or assume every result contains a final access token.

Keep issuance and redemption consistent

The send path and verification path both enforce whether the method is available. Directory-managed accounts cannot regain a local first-factor route through an older link. Send requests are limited by address and client IP; verification uses an IP-keyed limit so replacing the token value does not reset the guessing budget.

Links are secrets and expire. Keep them out of application logs and avoid presenting successful email submission as proof that the person received the message. The supplied flow owns expiry and refusal; your application owns the delivery configuration and user-facing recovery path.

Establish the phone before using it as proof

Phone enrollment uses phoneVerifySend(phoneNumber) and phoneVerifyConfirm(phoneNumber, code). Confirmation persists the verified phone on the credential record. This enrollment action does not itself sign the person in.

Send and submit the authentication challenge

The standard SmsOtpAuthMethod.tsx receives an authentication sessionId and uses it for both steps. The send handler calls getManualCallsHttpClient().smsOTPSend(sessionId); it does not let the person substitute an arbitrary destination for their verified phone. The submit handler then continues that same authentication session:

const handleVerify = useCallback(async (data: SmsOtpChallengeFormDto) => {
  clearCodeFormError();
  try {
    const response = await handleMfaVerify(sessionId, AuthMethod.SMS_OTP, data.code.trim());
    if (response.success) {
      onSuccess(response);
    } else {
      setCodeFormError(response.error || t(MfaChallengeLabel.ERROR_INVALID_CODE));
    }
  } catch (e: any) {
    setCodeFormError(e?.message || t(MfaChallengeLabel.ERROR_INVALID_CODE));
  }
}, [sessionId, handleMfaVerify, onSuccess, t, clearCodeFormError, setCodeFormError]);

This is the existing frontend challenge handler, not a complete standalone component. handleMfaVerify comes from the authentication flow, while onSuccess hands its response back to the parent. Failed verification stays in the challenge form; a successful code follows the server’s authentication result.

Enable the method and wire the provider

Start with the SMS delivery setup: enable EngineCapability.SMS, select the backend Twilio provider, synchronize its artifacts, supply TWILIO_CREDENTIALS and configure the sender number. Keep the secret in the backend deployment environment. The provider guide contains the complete configuration fragments; choosing an authentication method does not perform those steps.

In backend-api/src/saas-config.backend.ts, merge this policy into the intended userTypes.<type>.auth. Import AuthMethod from @wildo-ai/saas-models; existingMemberAuth is that type’s existing complete policy:

const memberAuth = {
  ...existingMemberAuth,
  authMethodsEnabled: {
    ...existingMemberAuth.authMethodsEnabled,
    [AuthMethod.SMS_OTP]: true,
  },
};

SMS can be a first or second factor. This declaration enables the method; it does not require MFA or weaken an existing MFA requirement. For a password-then-SMS flow, password must also be enabled and the first credential must succeed before the SMS challenge completes the session. If SMS should qualify as a second factor, include AuthMethod.SMS_OTP in mfaPolicy.acceptableMFAMethods and check mfaPolicy.requireStrongMFA within the same user-type authentication policy. Keep the MFA policy consistent with the factors the application intends to accept.

Set the challenge window and sending budgets

Wonder Todos supplies the following backend operational settings under auth.otpOperational.smsOtp. These are explicit example values, not a claim that enabling SMS installs a provider or enrolls a phone. Merge this entry alongside the existing email-OTP settings:

smsOtp: {
  otpLength: 6,
  expiryMinutes: 5,
  rateLimitBurst: 1,
  rateLimitHourly: 5,
},

The burst and hourly limits apply to the resolved phone destination; the SMS-send controller also enforces its own source-IP limit. Increasing a phone budget does not remove the source-IP gate. The phone-enrollment challenge is a separate flow with its own checks; these settings describe authentication SMS codes.

An accepted send is not evidence that the handset received the message. Complete the challenge on a controlled account to verify the real delivery path. A missing or expired authentication session, exhausted budget or provider refusal must not be reported as successful delivery.

The SMS backend service uses the provider’s request builder and response parser, validates the standard result and refuses provider-reported send failures.

Authentication issuance resolves the verified target, checks effective policy and applies delivery budgets. An older outstanding code is revoked when a replacement is created. Verification uses the authentication session and advances the normal flow after a successful comparison.

Respect the customer’s identity authority

An actively directory-managed account has local SMS authentication disabled by the effective policy, just as local passwordless methods are disabled. The phone belongs to the person and is not a revocable IdP secret, so the method’s policy is the barrier. Choose stronger factors when the account’s requirements call for independent device proof; SMS availability is not a claim that every security policy should accept it.

Configure more than the button

Enable AuthMethod.EXTERNAL_OAUTH2 for the user type, supply the provider connection and credentials, and permit social registration separately if new accounts may be created. The provider’s declared scope and supported profile mapping determine which identity is returned.

The connected provider setup joins the backend login declaration, application client ID, server secret, per-user-type method and exact callback address. Use those prerequisites together; a provider button is only the visible entry to that flow.

Choose sign-in and registration separately

Example: allow an existing member to use a social provider, while keeping new-account registration closed. In backend-api/src/saas-config.backend.ts, merge this into the member’s existing auth policy. existingMemberAuth represents that full policy; retain its password, session, lockout and MFA settings. Import AuthMethod and RegistrationMode from @wildo-ai/saas-models.

const memberAuth = {
  ...existingMemberAuth,
  authMethodsEnabled: {
    ...existingMemberAuth.authMethodsEnabled,
    [AuthMethod.EXTERNAL_OAUTH2]: true,
  },
  registration: {
    ...existingMemberAuth.registration,
    mode: RegistrationMode.DISABLED,
    allowedMethods: [],
  },
  autoLinkByEmail: false,
};

This example also disables automatic email-based linking. Existing linked identities can sign in; a matching email alone cannot attach a new identity to the account. This posture is for accounts whose external identity is already linked; it does not establish that first link. If intentional verified-email linking is required, review and enable autoLinkByEmail across the target account’s held user types instead. Registration policy governs new accounts; it does not remove existing identity links.

The initiating frontend must also allow the same member type in frontendServices.<service>.usersManagement with auth: true. To offer public social registration instead, use RegistrationMode.OPEN, include AuthMethod.EXTERNAL_OAUTH2 in registration.allowedMethods, and enable register for that frontend/user-type pair. These are additional admissions, not consequences of displaying a provider button.

Let the standard flow carry the proof

The standard authentication flow stores one-time state and, where supported, a PKCE verifier before redirecting. OIDC requests also carry a nonce. On return, Wildo consumes the state, exchanges the authorization code and binds the verified identity to the request. A returned ID token must pass validation even when the profile also comes from a user-info endpoint.

A custom frontend should start and finish this flow through the authentication client. A browser-supplied profile, matching email or successful redirect is not authentication evidence.

Link only after identity has been established

The service first looks for the external subject’s existing link. Verified email is required for email-based linking and new social provisioning. Unverified provider email is not treated as account ownership. Existing-account linking and new-account registration are different decisions; configure both intentionally.

Profile and pending-invitation reconciliation run through the account/provisioning services. Enterprise SSO remains a separate tenant-owned connection model. A social provider button does not by itself satisfy a customer’s requirement to control its organization’s identity provider.

Choose acceptable factors, not just an MFA switch

The factor must be enabled as well as accepted by the MFA policy. Put both declarations under userTypes.<type>.auth in backend-api/src/saas-config.backend.ts; changing only acceptableMFAMethods does not enable an authenticator.

Example: require an authenticator app after password sign-in. existingAdminAuth is the application’s existing complete policy. Import AuthMethod from @wildo-ai/saas-models and merge this result back into that user type.

const adminAuth = {
  ...existingAdminAuth,
  authMethodsEnabled: {
    ...existingAdminAuth.authMethodsEnabled,
    [AuthMethod.PASSWORD]: true,
    [AuthMethod.TOTP]: true,
  },
  mfaPolicy: {
    ...existingAdminAuth.mfaPolicy,
    requireMFA: true,
    requireStrongMFA: true,
    acceptableMFAMethods: [AuthMethod.TOTP],
    enrollmentGracePeriodDays: 0,
    passkeyExemptFromMFA: false,
  },
};

This example preserves other enabled first factors. Review those deliberately if the application must require password specifically. TOTP is a second factor, not an alternative first-factor login. The account must enroll it through the standard setup flow; enabling the method does not create a secret for anyone.

Decide what an external login must demonstrate

The same user type can receive social logins, whose evidence is assessed separately from native challenges. Set externalAssuranceEnforcement: ExternalAssuranceEnforcement.STRICT inside its mfaPolicy to refuse missing or insufficient required assurance; import the enum from @wildo-ai/saas-models. Omission means warn and audit, not strict refusal.

The TOTP-specific policy above cannot be satisfied merely by a provider saying “MFA happened.” Generic upstream MFA does not establish that a particular local factor was used. A configured enterprise OIDC connection instead delegates MFA enforcement to the customer’s IdP. It still must pass identity and token validation. Organization overrides can tighten the applicable policy; they cannot weaken strict enforcement.

Enrollment and verification are different steps

The TOTP setup service creates a secret, a QR-code URI and recovery codes. The person must prove a generated code before setup is marked verified. Recovery codes are shown for the person to retain; stored recovery values are hashed. TOTP acceptance atomically claims its absolute time step in Redis. Recovery-code consumption uses a conditional credential update, so a concurrent second consumption cannot also succeed.

The engine uses resolveAcceptedSecondFactorMethods for both offered and accepted methods. This prevents a flow from asking someone to enroll a factor that the next challenge refuses. In the native sign-in flow, the orchestrator carries the first-factor state into the second-factor step and issues the session after the required proof completes.

Registration completion is also distinct from a returning user’s login challenge. It can complete with an already-enrolled factor or under configured enrollment grace; otherwise it directs the person to enrollment.

Plan the recovery route

An enrolled TOTP code and an unused recovery code are checked through the same verification service. A used recovery code is removed from the stored set. The standard flow supplies enrollment and challenge interfaces; the application still decides which account types require protection and which factors are appropriate for their users.

Put the requirement on the operation

The engine’s user-deletion API variant declares both who may call it and the additional proof it requires. Selected fields from users.shared.resources-config.schemas.ts:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
admitsCrossSubjectUserAdministration: true,
riskLevel: ResourceOperationRiskLevel.CRITICAL,
requiresStepUpAuthentication: true,

riskLevel controls how danger is presented; it is not the reauthentication gate. requiresStepUpAuthentication is the explicit requirement. The role gate remains in force.

Exchange a fresh factor for an operation proof

The reauthentication service accepts password, an enrolled TOTP or recovery code, or a passkey assertion. Passkey step-up uses its own challenge and requires user verification, so a normal login assertion cannot be replayed as step-up.

After verifying the factor, AuthMethodManagementBackendService produces this proof:

const token = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.REAUTH,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: 5, unit: DurationUnit.MINUTES },
  userId: userId,
  resourceIdentifier: CoreResourceType.USERS,
  relatedId: userId,
});
return { reAuthToken: token.token };

The standard frontend’s StepUpAuthContext coordinates the challenge and pending action. The backend operation gate consumes the proof for the authenticated person; a custom interface needs the same continuation rather than treating the challenge as an independent login screen.

Keep policy and enrolled methods compatible

When the effective stepUpAuth policy is enabled, its methods constrains which factors may mint the proof. The resolver includes the actual subject’s organization memberships, so organization restrictions participate rather than reading only the raw user-type policy.

An operation’s explicit requiresStepUpAuthentication can require proof even when the policy-level switch is disabled; in that case the enabled-policy method restriction does not apply. The resource-operation gate covers direct user requests, with exemptions for worker execution, nested service calls and its declared read-operation set.

A person must have a factor the minting path accepts enrolled locally; an SSO identity alone is not a password, TOTP or passkey proof. A proof already minted remains usable until its short expiry even if the accepted-method policy changes in the meantime.

Start from the user-type policy

These overrides are authored in application configuration, not a per-customer settings record. Separately managed SSO connection settings govern provider routing and enforcement.

organizationTypes[type].authOverrides can describe authentication methods, MFA, password requirements and step-up policy. Registration, lockout and session length are not organization-overridable fields in this contract.

The pure resolveAuthConfig function resolves each organization’s override against the base and then combines the results. For password bounds, the actual merge uses:

function mergePasswordMostRestrictive(a: PasswordPolicyConfig, b: PasswordPolicyConfig): PasswordPolicyConfig {
  return normalizePasswordPolicyBounds({
    minLength: Math.max(a.minLength, b.minLength),
    maxLength: Math.min(a.maxLength, b.maxLength),
    requireUppercase: a.requireUppercase || b.requireUppercase,
    requireLowercase: a.requireLowercase || b.requireLowercase,
    requireNumbers: a.requireNumbers || b.requireNumbers,
    requireSpecialChars: a.requireSpecialChars || b.requireSpecialChars,
    expiryDays: mergeExpiryDays(a.expiryDays, b.expiryDays),
  });
}

Longer minimum length and shorter maximum/expiry represent different directions numerically but the same stricter intent. MFA requirement uses true-wins; a shorter enrollment grace period wins.

Decide how method changes are allowed

Across multiple organizations the resolved method sets are intersected. Do not assume that a method available in one membership remains available when another organization’s requirements are included.

Keep the effective policy at the point of use

The backend gathers relevant memberships and resolves policy for authentication and credential changes. Active directory management additionally disables local first-factor methods that would bypass the directory. Step-up methods can be narrowed and freshness shortened where a base step-up policy exists. Custom flows should use the effective policy rather than reading the user-type defaults alone.

Establish the connection and routing authority

The user type must enable AuthMethod.ORG_OPENID_CONNECT. The organization also needs an enabled SSO connection, client configuration and verified domain routing. Claiming a domain is not verification; DNS verification grants the routing authority. The application-scope connection has its own authorize path.

Connect the method, tenant and identity provider

Example: permit OIDC for a user type whose other authentication policy already exists. Merge into userTypes.<type>.auth in backend-api/src/saas-config.backend.ts. Import AuthMethod from @wildo-ai/saas-models.

const customerAuth = {
  ...existingCustomerAuth,
  authMethodsEnabled: {
    ...existingCustomerAuth.authMethodsEnabled,
    [AuthMethod.ORG_OPENID_CONNECT]: true,
  },
};

This permits the method; it does not create an IdP connection, verify a domain or grant membership. The initiating frontend must admit the same user type. Organization method policy can further restrict or expand available methods within the application’s declared rules.

Use the standard scoped connection configuration service for manual metadata, provider templates or discovery. Those modes supply issuer, endpoints and keys; they are not three different trust policies. Keep client secrets in the backend configuration/secret path and register the callback supplied for the selected scope and deployment.

Verify the returned identity

Wildo validates the ID-token signature, expected issuer, client audience, expiry and issuance time before trusting its claims. It binds the nonce to the request and the identity to the returned profile. Missing verification metadata refuses ID-token processing; an unverified decode is not a fallback.

If the connection declares acrValues, the verified token must contain an accepted acr. Requesting a value does not prove it was returned, and a generic amr list does not substitute for the requested authentication context. Delegated enterprise MFA does not bypass this explicit demand.

Connect authentication to provisioning

The enterprise provisioning service resolves the external subject, local account, profile and membership. Just-in-time creation follows configured provisioning rules; directory provisioning is a separate lifecycle channel for joiners and leavers. Enterprise OIDC accepts delegated MFA assurance from the configured customer identity provider; it does not claim Wildo observed individual factors. The customer owns the IdP’s authentication policy, while Wildo retains token validation, identity binding and local access checks. Callback completion uses its own admission path and does not enter the native second-factor continuation.

Keep local access policy deliberate

Enforced SSO, migration grace and named emergency accounts are policy choices on the scope’s configuration. Active directory management disables local first-factor paths that would bypass the customer’s directory. These decisions belong beside connection setup, not in a custom callback that silently falls back to a local password.

This capability makes Wildo a client of the customer’s identity provider. Wildo’s own OAuth authorization-server and delegated-agent access surfaces answer a different question.

Prepare both sides of the connection

Enable AuthMethod.ORG_SAML for the relevant user type and configure the scope’s SAML connection. Exchange the application’s service-provider metadata and the identity provider’s settings, including certificates and endpoints. The configured runtime must provide the XML-validation helper used by the SAML implementation.

Create the organization-owned SSO connection with protocol: SsoProtocol.SAML, a displayName, and the provider’s saml settings. The following excerpt from sso-connection.shared.schemas.ts shows the connection fields the settings form and request contract use:

saml: z.object({
  entityId: z.string().min(1).isAuditEvidence(),
  ssoUrl: z.url().isAuditEvidence(),
  sloUrl: z.url().optional().isAuditEvidence(),
  x509CertificatePem: z.string().min(1).optional(),
  x509Certificates: z.array(z.string()).min(1).isBackendOnly(),
  attributeMapping: z.object({
    email: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'),
    firstName: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'),
    lastName: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'),
    roles: z.string().optional(),
    department: z.string().optional(),
    employeeId: z.string().optional(),
    groups: z.string().optional(),
  }),
  signRequests: z.boolean().default(true).isAuditEvidence(),
  wantAssertionsSigned: z.boolean().default(true).isAuditEvidence(),

This is the relevant portion of the existing schema, not a complete connection payload. Enter the IdP’s entity identifier and SSO endpoint, supply its signing certificate through x509CertificatePem, and align attribute names with the assertions it sends. The backend derives the internal certificate array; clients do not write that backend-only field. Connection-level allowedDomains, defaultRole and autoCreateUsers govern who can enter and how new local accounts are provisioned.

On the provider side, use Wildo’s service-provider metadata for the intended organization. The metadata endpoint supplies that configuration; the assertion-consumer endpoint receives the provider’s response. Enable the connection and start sign-in through it: a valid assertion then enters the local account and membership resolution flow.

Bind the assertion before selecting the customer

SP-initiated sign-in carries request correlation. For IdP-initiated sign-in, the engine validates candidate connections against their configured certificates before selecting a scope. If several tenants share an identity provider and certificate, the signed audience must identify one intended tenant; unresolved ambiguity is refused.

Assertion conditions and replay protection are handled by the validator and replay guard. An unsigned issuer label is not tenant authority. Multiple configured certificates support certificate rollover without disabling validation.

Complete the account and logout lifecycle

After validation, the enterprise provisioning path resolves the local account and membership under the connection’s policy. SAML completion checks the local account and issues tokens on its callback path; it does not automatically enter the native MFA challenge continuation. Set the customer’s provider assurance requirements deliberately rather than assuming local mfaPolicy is translated into a SAML demand. Separate SAML logout paths manage the federated session behavior. Test the customer’s configured login direction and logout path with its provider; protocol support alone does not establish that a particular customer’s metadata and certificates are correct.

Configure session policy at the right level

Wonder Todos’ administrator type declares:

sessionDurationMinutes: 30,
maxConcurrentSessions: 3,

sessionDurationMinutes is the lifetime of the temporary sign-in episode, not the duration of the access JWT it eventually produces. Registration and invitation episodes are created with a 24-hour expiry; idle timeout and subsequent session-store updates also affect how long they remain usable. maxConcurrentSessions controls the number of authenticated sessions. JWT signing material and access/refresh token lifetimes are deployment-authored runtime settings.

Keep the refresh credential in its cookie

The standard client sends the refresh request with the HTTP-only refresh cookie. The endpoint takes an empty body; a JavaScript client should not read, store or submit the refresh token itself. Access-token updates are propagated to API clients and coordinated between same-origin tabs.

The controller reads the cookie after validating the request shape. Selected code from authentication-controller.backend.service.ts:

const ec = await this._getPreAuthExecutionContext();
RefreshTokenBodySchema.parse(req.body || {});
const refreshTokenValue = AuthControllerUtils.extractRefreshTokenFromCookie(req);
if (!refreshTokenValue) {
  throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
    customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_REFRESH_TOKEN_REQUIRED,
  });
}

Follow the order of the backend checks

AuthTokenIssuerBackendService.refreshAccessToken returns a cached successor when the predecessor is already marked as rotated and its grace entry exists. Concurrent refreshes select one successor in a Redis transaction that also records the retired credential and applies the winner’s session-limit effects. Losing requests receive the stored successor; they do not register extra sessions. If a response is lost after that transaction, a retry can recover the same tokens during the grace window. After the grace window expires, reuse of the retired credential writes the account-wide invalidation fence and reports a distinct reuse event. The raw token is not part of that signal.

Concurrent-session enforcement uses the shared session store and eviction path. A custom authentication integration must preserve these issuance and refresh paths; manually signing a replacement JWT would bypass the session lifecycle that makes the policy meaningful.

Use the account-wide revocation path

The authentication controller exposes logoutAll for the current user. Credential-reset services also use the issuer’s account-wide invalidation method. This is its current implementation:

public async invalidateAllTokensForUser(userId: string): Promise<void> {
  const nowSeconds = Math.floor(Date.now() / 1000);
  const refreshTokenDays = this.appConfigService.config.jwt.refreshTokenExpirationDays;
  await this.redisService.set(
    `${AUTH_REDIS_KEYS.TOKEN_INVALID_BEFORE}${userId}`,
    nowSeconds,
    { ttl: refreshTokenDays * 86400 },
  );
  this.logDebug('All tokens invalidated for user', { userId, invalidBefore: nowSeconds });
}

The fence expresses which earlier tokens are no longer admissible. The JWT guard, execution-context creation and refresh path consult it. A custom credential-changing flow must use the owning service rather than update the password hash and leave existing sessions untouched.

Choose the scope of logout deliberately

invalidateSession(sessionId) is the sibling for one login session. Account-wide invalidation affects the user’s earlier sessions; per-session invalidation withdraws only the selected one. Cross-tab logout separately clears the current browser’s visible state and client credentials.

Treat the revocation second as part of the boundary

The shared evaluateUserTokenInvalidationFence compares whole-second issuance times with the stored revocation second. It deliberately uses an inclusive comparison:

return { isRevoked: issuedAtSeconds <= invalidBefore, invalidBefore };

A token issued before the boundary is refused, and so is one issued in the same second. A login racing the revocation can therefore obtain a token that is immediately rejected: those timestamps cannot distinguish issuance just before the revocation from issuance just after it. Sign in again after that second has passed; do not relax the comparison or keep retrying the withdrawn token.

The atomic refresh publication path repeats the inclusive comparison inside Redis, so a revocation arriving while a successor is being signed is checked again before publication. Timestamp revocation, authorization-version changes and individual-session withdrawal are distinct checks; passing one does not bypass another. Test the equality case alongside an older token and a genuinely later issuance.

Understand the observed result

The next guarded request or refresh with a withdrawn token is refused. This does not reverse requests that already completed. Refresh checks revocation before returning a cached successor, so its short retry window cannot preserve access past a revocation. Keep the distinction between local interface cleanup, one-session logout and account-wide token withdrawal explicit in custom security controls.

The standard authentication provider coordinates tabs

AuthSessionContext uses the wildo-auth-tokens BroadcastChannel. Logout calls the backend, broadcasts LOGOUT, disconnects the live connection and clears local credentials. The receiver performs this selected cleanup from AuthSessionContext.tsx:

if (type === 'LOGOUT') {
  logDebug('Received logout signal from another tab');
  disconnect();
  tokenStorage.clear();
  getManualCallsHttpClient().setConsumableToken(null);
  setResourcesConsumableToken(null);
  storeAuthTokens(null);
  getManualCallsHttpClient().setAuthToken(null);
  setResourcesAuthToken(null);
  setAuth(EMPTY_AUTH_STATE);
}

Clearing both the manual HTTP client and resource client matters: an empty React account display alone would leave requests carrying an old credential. Consumable-token state is cleared as well. The receiving tab does not rebroadcast logout.

Use the shared provider in custom screens

Call the provider’s logout operation rather than removing a storage item yourself. Token refresh is coordinated on the same channel so tabs can adopt the new access token; the HTTP-only refresh cookie remains outside JavaScript.

Know the browser boundary

BroadcastChannel coordinates same-origin tabs where the browser supports it. It does not reach another device or unrelated domain. Backend logout is still the credential authority, and sign-out-everywhere is the separate account-wide mechanism. The sender clears its local state even if the network logout call fails, so a visibly signed-out tab is not by itself proof of server-side revocation.

Declare what the token is for

The password-reset service is a concrete consumer of the shared token mechanism. It mints this token before building the email link:

const resetToken = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.PASSWORD_RESET,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: PASSWORD_RESET_TOKEN_TTL_HOURS, unit: DurationUnit.HOURS },
  userId: user._id,
  resourceIdentifier: CoreResourceType.USERS,
  relatedId: user._id,
  metadata: { email: user.email },
});

Purpose, subject, related resource and expiration travel together. The reset handler later checks that the consumed token is a PASSWORD_RESET token before changing the credential. The token value is a secret, not a record identifier to display publicly.

Select the right lifecycle

Validation checks the current record. Consumption performs a conditional atomic mutation so two callers cannot both claim the last permitted use. Revocation is also guarded and makes an outstanding token unusable.

Reach it through the owning operation

Standard flows already supply their token consumers. Application operations can use declarative token generation, which reaches the same mint service. Define the intended resource/action target and the point of consumption; do not use a generic token as an implicit permission to call unrelated operations. Session-establishing links and upload grants add their own bounds above this shared lifecycle.

Connect generation to the action that needs proof

Wonder Todos pairs ASSIGN and CHANGE_STATUS in tasks.resources-config.ts. Its application-owned TasksManager_ConsumableTokenType.TASK_APPROVAL names the purpose (task_approval). The following is the generation block inside the existing ASSIGN API variant; its request declares assignedToUserId, and the operation requires ORG_MEMBER:

tokenGeneration: {
  tokenType: TasksManager_ConsumableTokenType.TASK_APPROVAL,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: 12, unit: DurationUnit.HOURS },
  grantedRoles: [{ roles: [CORE_ORG_ROLES.ORG_MEMBER], relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS }],
  userIdField: 'assignedToUserId',
  revokeExistingForSameRelated: true,
  createsOneOffSession: true,
  consumeAt: 'TARGET_OPERATION',
  targetingFields: { taskId: '_id' },
},

ConsumableToken_ConsumptionMode, DurationUnit, CORE_ORG_ROLES and ResourcePrimaryScope come from @wildo-ai/saas-models; the token-purpose enum belongs to the application. The generation helper reads the updated task: _id supplies the related record, assignedToUserId supplies the recipient and organizationId supplies the tenant. Reassignment replaces outstanding tokens of this purpose for that related record.

The matching CHANGE_STATUS variant already has its update request and organization-member role requirement. Its additional declaration is:

tokenAuthentication: {
  types: [TasksManager_ConsumableTokenType.TASK_APPROVAL],
  policy: TokenAuthenticationPolicy.ADDITIVE,
},

TokenAuthenticationPolicy is also exported by @wildo-ai/saas-models. ADDITIVE requires normal authentication plus the token; the token’s purpose, state and recipient are checked, and normal operation authorization still applies. ALTERNATIVE is a separate authoring choice that authenticates from the token context. Do not substitute it just to avoid supplying a signed-in session. In this ADDITIVE path, the recipient check does not compare the token’s task target with the task addressed by the request. An application that requires approval for exactly one record must enforce that match in its operation; targetingFields alone is not that authorization check.

Register the resource and deliver the generated secret

The task factory is registered under TasksManager_ResourceType.TASKS in tasks-manager.resource-configs.ts. The shared tasks-manager module contributes that map through resourceConfigurations, alongside resourceFieldIdentifiers and resourceRelationships. These declarations participate in the normal resource pipeline; they are not a second standalone token router.

Token generation also supplies additionalContext.tokenValue to configured notification dispatch. An authored notification/template must consume that value and deliver it to the intended recipient through a configured channel. Declaring generation does not by itself author an approval email, and the ordinary task-update response is not a secret-retrieval API. Keep the recipient selection, template and delivery configuration aligned with the generation branch.

This particular example opts into a one-off session and therefore uses the engine’s twelve-hour mint ceiling. With TARGET_OPERATION, exchange retains the consumable token for the target action. The exchanged session uses the account’s normal authorization; the targeting fields do not make its access JWT record-only. See one-off session links for that separate session contract. A workflow that does not need login should not opt into session creation merely to carry an action token.

Invoke the paired operations

For an existing task, use the application API base, organization/task IDs and an authorized member session. The assignment request supplies the recipient ID:

curl --fail-with-body -X PUT "$BACKEND_URL/organizations/$ORGANIZATION_ID/tasks/$TASK_ID/assign" \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"assignedToUserId\":\"$ASSIGNEE_ID\"}"

After the configured delivery reaches the assignee, APPROVAL_TOKEN is that generated secret and ASSIGNEE_ACCESS_TOKEN is their authenticated session. BACKEND_URL includes the API prefix. Change the same task’s status with both credentials:

curl --fail-with-body -X PUT "$BACKEND_URL/organizations/$ORGANIZATION_ID/tasks/$TASK_ID/change-status" \
  -H "Authorization: Bearer $ASSIGNEE_ACCESS_TOKEN" \
  -H "x-consumable-token: $APPROVAL_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"status":"completed","reason":"Approved by the assignee"}'

For ADDITIVE, put the secret in x-consumable-token; a consumable_token query parameter does not satisfy that requirement. Inspect the persisted status after success, then repeat with the spent token: it must no longer authorize a second consumption. Also check a missing token and a different recipient, alongside the successful authorized request. A failed attempt is only meaningful after the positive path has established that the task, session and delivery are valid.

Opt the account type in

Wonder Todos declares oneOffSessionAllowed: true for members. The create endpoint separately requires an application super-administrator, rejects self-issuance and checks that the target account is active. It is not a general organization-member impersonation permission.

Name the target and lifetime

Selected fields from the controller’s actual request schema:

userId: z.string().min(1),
tokenType: ConsumableTokenTypesSchema,
consumeAt: z.enum(['EXCHANGE', 'TARGET_OPERATION']),
consumptionMode: z.enum(ConsumableToken_ConsumptionMode).optional().default(ConsumableToken_ConsumptionMode.SINGLE_USE),
maxUses: z.number().int().min(1).optional(),
expiresIn: z.object({
  value: z.number().int().min(1),
  unit: z.enum(['minutes', 'hours', 'days']),
}).optional().default({ value: 1, unit: 'hours' }),
resourceIdentifier: z.string().optional(),
relatedId: z.string().optional(),

Single use is the default; the contract also supports explicit consumption mode and use bounds. consumeAt selects exchange or target-operation consumption. Resource and related-record fields belong to the consumable token’s redemption contract. With TARGET_OPERATION, the response retains that token for the operation that consumes it. They do not become resource or record restrictions on the exchanged access JWT: that session uses the account’s normal authorization. Choose the consumption path for the intended operation rather than treating a targeted link as a record-only login.

Bound the session as well as the link

The create path limits duration to the smaller of the account type’s configured ceiling and the engine’s twelve-hour absolute ceiling. The shared token mint enforces the absolute maximum for every session-establishing path. Exchange rechecks the target’s eligibility and anchors the session lifetime at consumption. The issuer caps the initial access token at that deadline and carries the same deadline through refresh rotation, so a late refresh does not extend the one-off session.

Link validity and session lifetime answer different questions: how long the invitation to enter may be used, and how long the resulting session may last. One-off sessions do not consume the person’s ordinary concurrent-session slots. The revoke path withdraws outstanding one-off tokens without treating an arbitrary password-reset or invitation token as a support link.

Keep request and completion separate

The request handler returns the same response for unknown, eligible and ineligible accounts. ACTIVE and PENDING_VERIFICATION accounts can receive a single-use password-reset token by transactional email; suspended, inactive and deleted accounts do not receive it. Auth_PasswordLost supplies the standard request and completion interface.

Apply the current account policy

The completion service consumes the token, verifies its purpose and resolves the account’s effective password policy. After validation, the actual credential-changing sequence is:

const newPasswordHash = await this.credentialVerifier.hashPassword(newPassword, this.appConfigService.config.auth.passwordHashing);
await this.tokenIssuer.invalidateAllTokensForUser(userId);
await this.credentialVerifier.updatePasswordHash(ec, userId, newPasswordHash);
await this.consumableTokenService.revokeTokensByRelatedId(userId, CoreConsumableTokenTypes.PASSWORD_RESET);

The hash is derived using configured password hashing. Earlier account tokens are withdrawn before the credential is written, and sibling password-reset links are revoked. A custom recovery screen should submit to this completion operation rather than update a user record directly.

Make the retry behavior understandable

The token is consumed before password-policy validation. A rejected replacement can therefore require another recovery email; the same link is not a reusable validation session. Present the known password requirements before submission and preserve the resend path.

A pending-verification account can receive recovery mail without becoming active. Restoring a suspended or deactivated account remains a separate lifecycle action. The completion endpoint limits requests to 10 per minute per IP before parsing or hashing; the request endpoint has its own throttles.

Use the dedicated administrative operation

The FORCE_PASSWORD_RESET variant is application-super-admin gated and explicitly admits a different target user. Its request and response contracts are selected here from users.shared.resources-config.schemas.ts:

requestDto: z.object({
  reason: z.string().min(1).max(500)
}),
customResponseDto: z.object({
  expiresAt: z.date(),
  sessionsRevoked: z.boolean()
}),

The custom implementation requires one addressed account, an attributable caller and a non-empty reason. Self-reset is refused here; the account owner’s normal password-change path proves their current credential instead.

Observe what the operation actually returns

expiresAt describes the emailed link and sessionsRevoked confirms withdrawal. Neither the reset token nor URL is returned to the administrator. The shared password-reset service sends to the target user’s email using the transactional template and resolved locale.

Separate containment from completion

Existing tokens are invalidated before the forced-reset flow completes. The user then follows the mail and chooses a password that meets their effective policy. Starting the reset is not evidence that the owner has received the email or changed the password yet. Delivery configuration and operational monitoring therefore remain necessary alongside the account action.

The backend refuses a deleted target. Reset initiation does not reactivate a suspended account or assign new roles; those are separate lifecycle decisions.

Choose the lifecycle action rather than patching status

The user resource declares separate operations for role assignment/revocation, suspension, unsuspension, reactivation and forced password reset. Generic updates do not stand in for those transitions.

Keep the actor and subject distinct

Administrative variants combine their role requirement with admitsCrossSubjectUserAdministration: true. That flag allows the target to be another user; it does not itself grant administrative authority. The same operation still has to satisfy its declared roles and any fresh-proof requirement.

The destructive user operation makes the combination explicit:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
admitsCrossSubjectUserAdministration: true,
riskLevel: ResourceOperationRiskLevel.CRITICAL,
requiresStepUpAuthentication: true,

These are selected fields from the real user-deletion variant, with comments omitted. Presentation risk and step-up enforcement are separate settings.

Preserve continuity and the record of change

The shared transition machinery owns status changes and scheduled reactivation cleanup. Administrative floors prevent removing the last usable administrator. reactivate_user requires a reason because it reverses the owner’s chosen departure, while unsuspension has a different contract. Custom administration screens should invoke these operations and display their outcomes, not write the underlying status and role fields directly.

Use the self-service resource for the current person

userSelf provides own-account reads and lifecycle actions over the user records. It does not expose arbitrary user-row updates. Profile and preference changes belong to their dedicated self-service resources.

The deactivation operation’s current request and availability condition are:

requestDto: z.object({
  reason: z.string().max(500).optional(),
}),
enabledCondition: ({ currentObject }) => {
  return currentObject.status === UserStatus.ACTIVE;
}

The shared transition moves ACTIVE to INACTIVE. The administrative continuity floor still applies, so the last usable administrator cannot bypass that protection by choosing the self-service route.

Explain the return path before deactivation

Normal authentication admits active accounts. Once deactivated, a person cannot simply sign back in to invoke self-reactivation. The administrative reactivate_user operation restores INACTIVE accounts with a documented reason. An imposed SUSPENDED account uses the distinct unsuspend operation.

Keep data-rights actions explicit

Account deactivation is not data erasure. This resource does not provide a self-delete or subject-export endpoint. Applications that offer those journeys need to connect their authorized data-rights process to the relevant services rather than relabel deactivation as deletion. This distinction preserves the user’s expectation and the lifecycle behavior behind the control.

Register custom roles in the application role configuration. inheritFrom supplies the existing responsibilities; relatedPrimaryScope selects the role table in which they are meaningful. Wonder Todos declares both an application manager and an organization supervisor:

This implementation excerpt from roles.ts shows the decision in context; explanatory source comments are omitted.

import { RolesConfiguration, ResourcePrimaryScope, CORE_APP_ROLES, CORE_ORG_ROLES } from "@wildo-ai/saas-models";

export const CUSTOM_ROLES_CONFIGURATION: RolesConfiguration = {
  'CUSTOM_APP_MANAGER': {
    role: 'CUSTOM_APP_MANAGER',
    inheritFrom: CORE_APP_ROLES.APP_USER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
  },
  'CUSTOM_ORG_SUPERVISOR': {
    role: 'CUSTOM_ORG_SUPERVISOR',
    inheritFrom: CORE_ORG_ROLES.ORG_MANAGER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS
  }
};

Register the role map with the shared application module

A role map must reach startup before operations can use its hierarchy. Wonder Todos’ shared-lib/src/engine/index.ts contributes it through the existing engine module:

import type { SharedSaaSModule } from '@wildo-ai/saas-models';
import { CUSTOM_ROLES_CONFIGURATION } from './roles';

const engineSharedModule: SharedSaaSModule = {
  moduleId: 'engine',
  kind: 'engine',
  customRoles: CUSTOM_ROLES_CONFIGURATION,
  // Keep the module's existing feature, milestone and product contributions.
};

export default engineSharedModule;

This selected module excerpt is the contribution point. In Wonder Todos, shared-lib/src/modules-registry.shared.ts includes engineSharedModule in sharedModules and passes that list to buildSharedSaaSModulesRegistry. Retain that existing assembly. Declaring the constant in an unreferenced file does not register roles. Membership assignment and an operation’s required roles are separate choices: registration makes the hierarchy available, it does not grant it to every account.

Follow the declaration into authorization

Application startup registers this configuration with initializeRolesWithCustom. The authorizer expands the caller’s role through the configured inheritance chain before comparing it with an operation’s roles. This means an inherited manager responsibility remains available without copying the entire role list onto every member.

A matching role is one part of admission. Tenant confinement and reference eligibility still apply. APP_PUBLIC is an operation declaration that removes a role requirement; it is not a role to grant to an account. Use role grants to control who may assign the roles you define.

The OAuth-client mint handler checks the caller-authored roles before generating secret material. The core create still performs persistence, and the postfix returns the plaintext secret once:

This implementation excerpt from oauth-clients.custom-impl.backend.service.ts shows the decision in context; explanatory source comments are omitted.

export function buildOAuthClientMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): OAuthClientImplHandlers {
  return {
    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);
      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);
      PLAINTEXT_SECRET_BY_EC.set(executionContext, plainSecret);
      return { ...(input as Record<string, unknown>), secretPrefix, hashedSecret };
    },
    postfixCoreOperations: async (_id, createdClient, executionContext, _operationPath, _utils) => {
      if (!createdClient || typeof createdClient !== 'object') return createdClient;
      const plainSecret = PLAINTEXT_SECRET_BY_EC.get(executionContext);
      PLAINTEXT_SECRET_BY_EC.delete(executionContext);
      if (!plainSecret) return createdClient;
      return { ...(createdClient as Record<string, unknown>), plainSecret };
    },
  };
}

Extend the same check to application resources

The framework wires assertRequestedRolesWithinCallerCeiling into its membership, unit-assignment, application-role and credential creation paths. If an application introduces another resource whose caller-settable roles confer authority, call the assertion from its create and roles-changing update handlers too.

Use createRoleHierarchyResolver to read the live, application-configured hierarchy. Pass the roles as the caller authored them, before adding policy defaults. Otherwise a default role supplied by the framework would be mistaken for a privilege the person asked to grant.

Keep scope and privilege checks separate

The ceiling compares effective roles across the caller’s organization-wide memberships. A unit-scoped administrator role does not become organization-wide grant authority. The surrounding operation authorization answers where the caller may write; this check answers how high they may grant.

Internally initiated provisioning and an application-scoped super-administrator are deliberate exceptions. Credential roles are fixed at creation: rotation changes secret material, not the roles the credential carries.

Role and account-status changes use the transition guard; removals use the removal guard. Both reach the same population check. This part of that check shows how it excludes the accounts being changed:

This implementation excerpt from super-admin-floor.backend.utils.ts shows the decision in context; explanatory source comments are omitted.

export async function assertSuperAdminFloorPreserved(params: {

  subjectUserIds: readonly string[];
  cause: SuperAdminFloorReductionCause;
  executionContext: ExecutionContext<any>;
  repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
  errorBuilder: ErrorBuilderBackendService;
  conferringRoles: readonly string[];
  operationIdentifier: string;
}): Promise<void> {
  const { subjectUserIds, cause, executionContext, repositoriesRegistry, errorBuilder, conferringRoles, operationIdentifier } = params;

  const remainingUsableSuperAdmins = await countOtherUsableSuperAdmins({
    excludedSubjectIds: subjectUserIds,
    executionContext,
    repositoriesRegistry,
    errorBuilder,
    conferringRoles,
    operationIdentifier,
  });

  if (remainingUsableSuperAdmins >= SUPER_ADMIN_FLOOR_MINIMUM) return;

  throw errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
    context: {
      code: AdministrativeContinuityErrorCode.LAST_APPLICATION_SUPER_ADMIN,
      reason: SUPER_ADMIN_FLOOR_REFUSAL_REASON,
      message:
        'Refused: this would leave the application with no usable super-administrator. '
        + SUPER_ADMIN_FLOOR_REMEDY,
      cause,
      operationIdentifier,
      subjectUserIds: [...subjectUserIds],
      remainingUsableSuperAdmins,
      requiredUsableSuperAdmins: SUPER_ADMIN_FLOOR_MINIMUM,
      conferringRoles: [...conferringRoles],
      usableStatuses: [...ADMINISTRATIVELY_USABLE_USER_STATUSES],
    },
  });
}

Treat the refusal as a state conflict

The caller may have all the required permissions and still be unable to perform this change. The response is a conflict with LAST_APPLICATION_SUPER_ADMIN, because the problem is the resulting administrator population. Promoting another usable account is the remedy; acquiring another permission is not.

Custom roles that confer super-administrator authority participate through the live role hierarchy. A disabled or otherwise unusable account must not be counted as the fallback simply because its stored roles still look powerful.

Preserve continuity on the right lifecycle path

The account-role administration handlers call the guard when authority or usability decreases. Subject erasure has a separate continuity path: do not replace a privacy erasure workflow with a blanket refusal. Organization ownership has its own last-owner rule, because tenant ownership and application administration are different responsibilities.

ResourcePrimaryScope names the resolved scope. Application authors declare ownership through relationships; the resource factory derives resourcePrimaryScope from that declaration. Scope-root resources anchor themselves, and polymorphic resources receive the relationship for their selected scope variant. Operation roles then decide who can act within the resolved scope.

Declare the ownership that determines the scope

Wonder Todos registers this relationship alongside its resource definitions. The parent is an organization, the child is a todo, and isPrimaryScope identifies the ownership relationship used to derive the child’s scope. Source: tasks-manager.relationships.ts; source comments omitted.

createResourcesRelationship(
  CoreResourceType.ORGANIZATIONS, TasksManager_ResourceType.TODOS,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'organizationId',
    contextPolicy: {}
  }
)

With this registered relationship, the factory resolves organization ownership and its foreign-key field. Another relationship, such as the todo’s assignee, remains a reference; it does not replace the primary owner. An ordinary resource without a resolvable primary scope is rejected during configuration instead of silently receiving a broader scope.

Let a draft belong to a person or a visitor

Wonder Todos’ draft notes demonstrate USER_SELF and ANONYMOUS without changing the business object. The schema declares nullable userId and anonymousUserId foreign keys, both excluded from ordinary updates. The resource opts into anonymous ownership with isAnonymizable: true and chooses transpositionPolicy: ResourceTranspositionPolicy.ADD for the later account handoff.

Its authored relationship starts from the signed-in person. This is the relevant declaration from tasks-manager.relationships.ts, including the child lifecycle decision:

createResourcesRelationship(
  CoreResourceType.USERS, TasksManager_ResourceType.DRAFT_NOTES,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'userId',
    parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
    accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT,
    childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE } } },
    contextPolicy: {},
  }
)

The relationship helper and enum vocabularies come from @wildo-ai/saas-models; TasksManager_ResourceType is application-owned. OPTIONAL accommodates a visitor-owned row without a userId; it does not make another person’s records public. The anonymizable resource factory supplies the anonymous ownership relationship. Application authors do not hand-author a second unrelated draft resource.

The draftNotes_ResourceConfiguration_InitializationFactory is registered in the tasks-manager resource factory map, and the shared module contributes that map together with its relationships and field identifiers. Its ordinary create/read/list/update/delete API variants accept APP_USER and APP_ANONYMOUS; ownership confinement still applies to each caller. Allowing both roles does not merge their records.

Observe the two ownership paths

With BACKEND_URL including the API prefix, an authenticated person lists their drafts using their own user ID and Bearer session:

curl --fail-with-body "$BACKEND_URL/users/$USER_ID/draft-notes" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

For an already established anonymous session, use its UUID in the path and its signed session token in the header. The UUID is an identifier, not a credential:

curl --fail-with-body "$BACKEND_URL/anonymous-users/$ANONYMOUS_UUID/draft-notes" \
  -H "x-anonymous-session: $ANONYMOUS_SESSION_TOKEN"

The standard client establishes and carries that session; anonymous sessions and transposition explains its lifecycle. Supply the application’s frontend-service header where its deployment requires it. Neither call turns a user-supplied owner field into authority.

Verify isolation using existing disposable drafts: each owner can read their own record; substituting another user or visitor’s path/record must not expose or mutate that record. Check the allowed read first so an unavailable route cannot masquerade as successful isolation. The existing scope-isolation-user-anon-hostile.e2e.ts exercises these separate ownership paths and re-reads storage after denied mutations.

Carry the scope through the operation

The framework resolves the scope root and contextual identifier, builds the caller’s execution context and uses the matching authorization path. A user-scoped resource is not made accessible to everyone merely because it sits in the same application database.

Organization units narrow authority inside an organization; they do not introduce a fifth primary scope. Likewise, a directory of users is an application administration surface, not the same interaction as reading one person’s own preferences.

Plan the visitor-to-account transition

Anonymous ownership can support work before registration. A resource’s transposition policy determines whether that work is reassigned, replaces existing work or is discarded when ownership moves. Treat that transition as a separate product decision from who may operate on the visitor’s data now.

See tenant confinement for organization records and anonymous sessions for the registration handoff.

Register the primary ownership relationship with the application’s resource relationships. The resource factory derives organization scope from it; resourcePrimaryScope is not a second author-maintained setting. In Wonder Todos, tasks-manager.relationships.ts contains this declaration (source comments omitted):

createResourcesRelationship(
  CoreResourceType.ORGANIZATIONS, TasksManager_ResourceType.TODOS,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'organizationId',
    contextPolicy: {}
  }
)

The todo schema supplies the organizationId foreign-key field. The relationship connects that field to the organization parent and makes it the primary ownership axis. Register it before initializing the resource configuration, alongside the resource’s operations and other relationships.

When an authorized caller lists todos through the organization’s contextual resource operation, the framework resolves that organization in the execution context and carries confinement into the repository query. The same declaration serves both persistence adapters. Application code still supplies the operation’s roles and business filters; it does not infer tenant authority from a submitted organization ID.

The shared confinement function checks the authenticated organization and the operation’s declared crossing policy before adding the top-level ownership predicate:

This implementation excerpt from initiator-organization-confinement.backend.ts shows the decision in context; explanatory source comments are omitted.

export function assignInitiatorOrganizationConfinementToFilter<TFilter extends object>(params: {
  readonly filter: TFilter;
  readonly executionContext: InitiatorOrganizationConfinementSignal;
  readonly blacklistedFields: ReadonlySet<string>;
  readonly mainSchema: unknown;
  readonly schemaPaths: InitiatorOrganizationConfinementPathResolver;
  readonly isFieldPersisted: (fieldName: string) => boolean;
}): boolean {
  const initiatorOrganizationId = params.executionContext.initiatorIds?.organizationId;
  if (!initiatorOrganizationId) {
    return false;
  }

  if (params.executionContext.operation?.admitsCrossTenantPlatformAdministration === true) {
    return false;
  }

  if (
    params.blacklistedFields.has(INITIATOR_ORGANIZATION_CONFINEMENT_FIELD)
    || !params.isFieldPersisted(INITIATOR_ORGANIZATION_CONFINEMENT_FIELD)
  ) {
    return false;
  }

  const organizationPaths = params.schemaPaths.findNestedFieldPathsFromZodSchema(
    params.mainSchema,
    INITIATOR_ORGANIZATION_CONFINEMENT_FIELD,
  ).filter((fullPath) => !fullPath.includes('.'));

  let applied = false;
  organizationPaths.forEach((fullPath) => {
    if (!params.schemaPaths.hasNestedPath(params.filter, fullPath)) {
      params.schemaPaths.setNestedValue(params.filter, fullPath, initiatorOrganizationId);
      applied = true;
    }
  });

  return applied;
}

Follow authority, rather than trusting a payload

The execution-context creator obtains memberships and removes authority from organizations that are no longer operational. The normal create path supplies contextual ownership fields; client data is not the authority for which tenant owns the new record.

Both persistence adapters call the shared confinement authority. A nested field that happens to be named organizationId is ordinary data unless it is the declared top-level ownership axis; filtering every matching field name would hide legitimate records.

Use the declared exceptional path

A deliberately admitted cross-tenant platform operation can step outside normal confinement. That is an operation-level declaration with its own admission requirements, not a global super-administrator shortcut. Arbitrary direct database access is outside the resource path and must not be mistaken for an authorized resource operation.

Organization listings need an additional rule because the organization is the scope root itself: see account-list confinement.

A machine token names its scope. The execution-context creator compares the addressed scope with that authenticated value before constructing the request context:

This implementation excerpt from execution-context-creator.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const urlScopeId = machineScope === ResourcePrimaryScope.ORGANIZATIONS
          ? initiatorCriticalParamsValue.organizationId
          : initiatorCriticalParamsValue.applicationId;
        if (urlScopeId && urlScopeId !== machineToken.scopeId) {
          throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined,
            { customMessageReference: ErrorCustomMessageReference.AUTHORIZATION_MACHINE_SCOPE_MISMATCH,
              context: { reason: 'machine_scope_url_mismatch', tokenScope: machineScope } });
        }

        const machineCredential = { authMethod: MachineAuthMethod.OAUTH_CLIENT, credentialId: machineToken.clientId };
        const initiatorIds: ExecutionContext_InitiatorIds = machineScope === ResourcePrimaryScope.ORGANIZATIONS
          ? { ...this.extractInitiatorIds(initiatorCriticalParamsValue), organizationId: machineToken.scopeId, machineCredential }
          : { ...this.extractInitiatorIds(initiatorCriticalParamsValue), applicationId: machineToken.scopeId, machineCredential };

Keep ownership fields server-authored

Generated operation input shapes exclude contextual ownership fields from normal caller-controlled data. The resource operation path then enriches the write using its resolved context. Build scoped API calls with the intended organization in the route and ordinary business fields in the payload; do not rely on a payload organizationId to establish authority.

The exact refusal depends on the stage: invalid identity, inaccessible scope and disallowed input are different cases. Do not interpret an ignored extra property as proof that it was trusted.

A reference inside the payload still has its own eligibility question. Membership-constrained relationships prevent a valid tenant write from linking an ineligible person or partner.

This is the task-assignee declaration in Wonder Todos. scopeMembership: true asks the registry to resolve the organization-membership junction. The context settings separately control the related information returned with the task:

This implementation excerpt from tasks-manager.relationships.ts shows the decision in context; explanatory source comments are omitted.

createResourcesRelationship(
    TasksManager_ResourceType.TODOS, CoreResourceType.USERS,
    ResourceRelationshipCardinality.MANY, ResourceRelationshipCardinality.ONE,
    {
      nature: RelationshipNature.REFERENCE,
      foreignKeyField: 'assignedToUserId', // Explicit for Edge Case #1 - multiple FKs to same type
      parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
      accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
      scopeMembership: true,
      contextPolicy: {
        objectMode: ContextPolicy_ObjectMode.SUMMARY,
        operationOverrides: {
          [CoreResourceOperation.READ]: { objectMode: ContextPolicy_ObjectMode.FULL },
          [CoreResourceOperation.LIST]: { enabled: false },
          [CoreResourceOperation.SEARCH]: { enabled: false },
        }
      }
    }
  ),

Use an explicit junction when membership means something else

For a rota or partnership, set scopeMembership to an object naming the junction. junctionScopeField and junctionTargetField identify its columns when they cannot be inferred. The target’s existence and the junction’s existence answer different questions; both matter.

Create and update integrity checks evaluate referenced foreign keys before storing the write. An operation can add referenceConstraints to tighten eligibility, such as requiring a particular membership status. Related-record resolution uses the declared membership semantics as well.

Separate who may assign from who may be assigned

Wonder Todos’ assign-lead operation uses the same assignedToUserId relationship shown above and declares an active organization administrator as its eligible target. The caller must also be an administrator. The example below uses built-in organization roles: permission to make the change does not make every selected person eligible.

This is the operation declaration from todos.resources-config.ts, with comments omitted. Todos_Operations belongs to the application; the other enums come from @wildo-ai/saas-models, and z comes from zod.

[Todos_Operations.ASSIGN_LEAD]: {
  variants: [
    {
      variantType: ResourceOperationVariantType.API_CALL,
      isDefault: true,
      roles: [CORE_ORG_ROLES.ORG_ADMIN],
      riskLevel: ResourceOperationRiskLevel.MEDIUM,
      resourceOperationLike: CoreResourceOperation.UPDATE,
      requestDto: z.object({
        assignedToUserId: z.string().min(1),
      }),
      referenceConstraints: {
        assignedToUserId: {
          qualifyingStatuses: [OrganizationMemberStatus.ACTIVE],
          requiredRoles: { scope: ResourcePrimaryScope.ORGANIZATIONS, roles: [CORE_ORG_ROLES.ORG_ADMIN] },
        },
      },
    },
  ],
},

Place this inside the resource’s operationsConfiguration. The shared tasks-manager module contributes its factory map through resourceConfigurations and its relationship list through resourceRelationships. Both are needed: the relationship identifies the membership junction; this operation adds the eligibility criteria. Merely adding an input field does not declare that relationship.

For an existing todo, call the addressed operation with the organization’s administrator session. API_BASE includes the backend API prefix; ASSIGNEE_USER_ID is the selected user’s ID, not their membership ID.

curl --fail-with-body --request PUT "$API_BASE/organizations/$ORGANIZATION_ID/todos/$TODO_ID/assign-lead" \
  --header "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"assignedToUserId\":\"$ASSIGNEE_USER_ID\"}"

Run the permitted case before testing refusals, and confirm refused writes leave the previous assignee unchanged. The ordinary assign operation on this resource does not add these status/role criteria: it retains the relationship’s membership check. If several operations must enforce the stricter policy, declare it on each applicable variant.

Target roles are resolved against the application’s current role definitions in the declared scope. A custom role can qualify through its inheritance; an unknown role grants nothing. Related-record search can offer members who do not meet a stricter write policy, so handle an assignment refusal even when the person appeared in a picker.

Make exceptions deliberate

This policy is opt-in on the relationship. An organization-less target without it may receive an existence check rather than a membership check. A variant that explicitly waives membership changes the contract for that variant; do not use that escape hatch to make an ordinary assignment work around an incomplete declaration.

The same scope-root authority is used by authorization and repository filtering. After identifying a governed organization collection operation, it derives the allowed IDs from the caller’s organization-wide role entries and intersects the requested IDs:

This implementation excerpt from scope-root-collection-confinement.backend.ts shows the decision in context; explanatory source comments are omitted.

function intersectRequestedIdsWithMembership(requested: unknown, membershipIds: readonly string[]): string[] {
  if (requested === undefined || requested === null) return [...membershipIds];

  const membership = new Set(membershipIds);

  if (typeof requested === 'string') {
    return membership.has(requested) ? [requested] : [];
  }

  if (Array.isArray(requested)) {
    return requested.map(String).filter((id) => membership.has(id));
  }

  if (typeof requested === 'object') {
    const operators = Object.keys(requested as Record<string, unknown>);
    const inValue = (requested as { $in?: unknown }).$in;
    if (operators.length === 1 && operators[0] === '$in' && Array.isArray(inValue)) {
      return inValue.map(String).filter((id) => membership.has(id));
    }
    return [];
  }

  return [];
}

Know which operations are set-shaped

The confinement covers list, search, count, update-many and delete-many operations on the organization root. Addressed reads have a separate per-record authorization path. A unit-only role does not become permission to enumerate the whole organization.

The portable empty-set predicate produces no results on either database adapter. A caller-supplied condition is never a reason to drop the membership restriction.

Distinguish tenant lists from application directories

Other scope roots have explicit dispositions: the deployment application row, the person directory and anonymous sessions do not share the same tenant-membership filter. Application-wide directory admission has its own elevation policy. Internally initiated work, verified callbacks and deliberately admitted cross-tenant operations also have distinct handling; an empty membership list must not silently empty a framework maintenance sweep.

Role checks that do not depend on the row can refuse before resolving it. A missing or scope-invisible addressed record uses the same outward not-found treatment. Internal storage faults remain faults rather than being rewritten as evidence that a record is absent.

Keep a useful refusal trail

authorization-denial-audit.backend.utils.ts classifies authorizer-origin not-found outcomes as authorization refusals while excluding unrelated application 404s. The audit policy emits the first refusal and escalating occurrence counts, rather than writing an attacker-controlled number of rows.

The resource-operation authorization path uses this classifier to distinguish a concealed subject from an unrelated application failure. Exact excerpt from authorization-denial-audit.backend.utils.ts:

export function classifyAuthorizationDenial(
  error: unknown,
  phaseDefaultReason: ResourceOperationDenialReason,
): ResourceOperationDenialReason | undefined {
  if (!isWildoBackendError(error)) return undefined;

  if (error.type === ErrorType.AUTHORIZATION) {
    return error.customMessageReference === ErrorCustomMessageReference.AUTHORIZATIONS_MISSING_INITIATOR
      ? ResourceOperationDenialReason.MISSING_INITIATOR
      : phaseDefaultReason;
  }

  if (
    error.type === ErrorType.NOT_FOUND &&
    error.customMessageReference === ErrorCustomMessageReference.AUTHORIZATIONS_VALIDATION_FAILED
  ) {
    return ResourceOperationDenialReason.SUBJECT_NOT_RESOLVABLE;
  }

  return undefined;
}

The second branch recognizes only a not-found outcome marked by the authorizer. Other failures return undefined here; they keep their own error handling rather than entering the access-refusal series.

The counter is associated with the available user identity, resource, operation, variant and reason; calls without a user identity share the fallback bucket. Walking different target IDs therefore does not create an independent audit bucket for every guessed record.

Do not confuse observation with prevention

The normal authorization decision refuses the request. The audit volume policy does not rate-limit or lock the caller, and it does not normalize response timing. Security monitoring can act on the recorded pattern; application access rules remain the preventive control.

The resource exposes requestAccess, approve, deny and revoke. The request supplies justification and requested duration; operator identity, status and expiry are server-authored. Default duration is one hour and the server caps requests at four hours.

Admission checks the actual expiry, not whether a background process has relabelled the row:

This implementation excerpt from platform-access-grants.shared.schemas.ts shows the decision in context; explanatory source comments are omitted.

export function isPlatformAccessGrantUsable(
  grant: Pick<PlatformAccessGrant, 'status' | 'expiresAt'> | undefined,
  now: Date,
): boolean {
  if (!grant) return false;
  if (grant.status !== PlatformAccessGrantStatus.ACTIVE) return false;
  return grant.expiresAt instanceof Date
    ? grant.expiresAt.getTime() > now.getTime()
    : new Date(grant.expiresAt).getTime() > now.getTime();
}

Declare the operation that support may use

The crossing flag belongs to an API operation variant. The built-in ownership-repair operation keeps the role, scope permission and request together:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
riskLevel: ResourceOperationRiskLevel.CRITICAL,
resourceOperationLike: CoreResourceOperation.UPDATE,
admitsCrossTenantPlatformAdministration: true,
requestDto: z.object({ justification: z.string().min(1).max(1000) }),

This is a selected variant fragment from organization-members.shared.resources-config.schemas.ts, not a standalone resource. Its operation enums and roles come from @wildo-ai/saas-models, with z from zod. The existing membership resource registers this operation. A custom support action needs its own registered resource operation, API variant and implementation; copying the flag alone creates neither a route nor business behavior.

Choose whether the customer must approve

platformAccessApprovalRequired is a field on the organization record, with a default of false. It is not an organization-type authentication override or a caller-supplied grant status. Set it through the authorized organization configuration path before support requests arrive. The request handler reads the stored organization posture and checks whether a usable owner can approve.

Request, decide, then perform the action

The following sequence follows Wonder Todos’ platform-access-grant lifecycle example. ORG_ID comes from the customer support case; ordinary organization listing is not a platform-wide customer directory. OPERATOR_TOKEN belongs to an application super-administrator. CUSTOMER_ADMIN_TOKEN belongs to a tenant administrator with authority to decide the request. Use a customer with approval required and a usable owner for this pending-approval example.

curl "$BACKEND_URL/organizations/$ORG_ID/platform-access-grants/request-access" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"justification":"Investigate support case SUP-42","requestedDurationMinutes":30}'

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/platform-access-grants/$GRANT_ID/approve" \
  -H "Authorization: Bearer $CUSTOMER_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"decisionReason":"Verified support case SUP-42"}'

Take GRANT_ID from the created grant record’s _id. Check its returned status and expiry: accepting the request does not mean access is active. With the example’s posture it waits for the tenant decision, and the operator’s crossing is refused while pending. The request operation itself has a narrow bootstrap exemption so an operator can ask without already holding the grant.

Approval uses the customer’s authority, not the operator’s platform crossing. For a refused request use the grant’s deny operation; to withdraw an existing grant use revoke. These are lifecycle operations, not edits to status or expiresAt. A usable grant is looked up when the operator calls the target operation; it is not a replacement login token to send as a Bearer credential.

Continue with the ownership-repair invocation for an actual declared target operation. The grant remains limited to its operator, organization and time window; it does not admit undeclared actions.

Apply both admission requirements

The target operation must declare that it admits cross-tenant platform administration, and the operator must have a usable grant for the target account. A grant does not turn every operation into a support door. Grant lookup failures do not restore standing access.

The last case prevents an ownerless account from becoming impossible to repair. Approval posture and owner usability are checked on the request path, not copied from the caller.

Separate account support from global administration

Approval and denial use the tenant’s own authority; the platform crossing declaration does not let an operator approve on that basis. Application-wide directory access has a separate grant and two-person approval policy because no single tenant can authorize reading a deployment-wide directory.

The settings hub selects an organisation; its registered resource operations keep that owner in the request path and execution context. The backend validates who may use those operations. Selecting a customer in the interface does not itself grant authority over that customer’s resources.

For SSO, configuration and connections are separate resources under the same owner. Domain verification establishes who controls the sign-in domain; connection settings describe how the identity provider participates. Neither should be copied into an application-wide credential merely because the application hosts both customers.

Exercise an organization-owned configuration operation

For example, the SSO domain-claim operation lets the organization’s administrator begin proving a domain it controls. The organization already has its seeded SSO configuration; claiming a domain does not require creating a second configuration row.

This request follows sso-domain-ownership.e2e.ts. Set BACKEND_URL, ORGANIZATION_ID and the organization’s administrator ACCESS_TOKEN; replace the illustrative domain with one the customer controls.

curl -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/claim-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

The claim response names the domain, reports pending and returns dnsName plus the one-time dnsRecordValue. Publish that exact value as a TXT record at the returned name. Do not invent the challenge value or assume that the domain’s presence in the stored list means it is verified.

After publishing the record, ask the same scoped operation family to verify it:

curl --fail-with-body -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/verify-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

Read the response’s status, not only the HTTP status code. A completed verification request can return HTTP 200 with failed; --fail-with-body cannot detect that business result. The backend checks DNS and rechecks competing ownership at verification time, before granting routing authority. A claim alone does not authorize sign-on routing.

This illustrates the ownership contract: a public, named operation changes the selected organization’s configuration and returns the next action its administrator needs. Provider connection details and SSO enforcement remain separate settings; the general configuration update is an internal operation, not a public catch-all HTTP endpoint.

Configure the correct integration owner

Enable the relevant feature and configure the provider through its declared resource. A page appearing in settings is a consumer of that configuration, not proof that a provider is already connected or operating.

Preserve the distinction between personal and organization connections

A person’s connected account and an organization-owned credential represent different authority. Use the appropriate resource and runtime context rather than copying credential material into generic application settings.

This capability describes the integrations with organization-owned configuration. It does not imply that every external provider supports every ownership mode. See the individual sign-on, provisioning and machine-access guides for their setup and operation contracts.

Separate account creation from sign-in

This real member registration policy in Wonder Todos requires email verification before access:

registration: {
  mode: RegistrationMode.OPEN,
  allowedMethods: [AuthMethod.PASSWORD],
  emailVerification: EmailVerificationMode.REQUIRED_BEFORE_ACCESS,
  blockForSSODomains: false,
},

allowedMethods is the acquisition set. authMethodsEnabled is the sign-in set. The frontend’s usersManagement entry must also allow registration for this user type. A method being available to an existing member does not automatically make it a signup method.

Follow the selected method’s next step

The public registration service returns the appropriate next step. A passkey proves possession of an authenticator, not ownership of an email address, so passwordless public signup does not skip email proof even when deferred verification is selected for password registration.

Complete the surrounding onboarding

User-type roles and configured organization creation are separate parts of the signup result. Use the standard registration flow or follow its returned state with a custom interface; do not issue your own session immediately after creating a user row. Your application chooses the profile and onboarding information, while Wildo connects account status, verification and authentication.

The pending membership is the invitation

An invitation is an organization-member record in the INVITED state. Acceptance activates that membership instead of creating a disconnected invitation history and another membership by hand. The organization’s member operations own invitation creation, role assignment and revocation.

Create, resend or cancel the same invitation

Use an organization administrator’s token and the target workspace ID. The email-based CREATE path resolves the invited account and creates the pending membership; do not supply userId or force a lifecycle status:

curl "$BACKEND_URL/organizations/$ORG_ID/organization-members" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"userEmail":"colleague@example.com","roles":["ORG_MEMBER"]}'

Read the created membership and retain its _id as MEMBERSHIP_ID. Confirm its status is INVITED. The caller must be allowed to grant the selected roles, and those roles must fit the organization type. A successful create is not evidence that the recipient received an email: delivery also needs the application’s configured email provider and invitation templates.

If the invitation remains pending, resend it on that same record:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/organization-members/$MEMBERSHIP_ID/resend" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{}'

Resending replaces the acceptance token and invalidates the previous link. To withdraw the invitation instead, use its revoke operation:

curl -X DELETE "$BACKEND_URL/organizations/$ORG_ID/organization-members/$MEMBERSHIP_ID/revoke" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"The invitation is no longer needed"}'

The optional reason is limited to 500 characters. Both resend and revoke require a still-pending membership and organization-administrator authority. Revocation removes that invitation and revokes its acceptance token; it is not the operation for removing an already active member. For an acceptance check, use the newest invitation link or the signed-in invitee’s own inbox, then verify the membership becomes ACTIVE. Do not run revoke before testing acceptance on the same invitation.

Match the acceptance path to the person

The registration service first validates the token and current membership, then checks the selected method against the effective invitation policy. Token consumption is deferred until the guarded acceptance transition, so validation does not itself accept an invitation.

Keep existing users on their current account

The standard invitation screen uses the authenticated client and refreshes organization context after acceptance. This is its handler in AppPage_InvitationsSettings.tsx, with comments omitted:

const handleAccept = useCallback(
  async (membershipId: string) => {
    setBusyId(membershipId);
    setError(null);
    try {
      await getManualCallsHttpClient().acceptMyInvitation(membershipId);
      await refreshOrganizations();
      setSuccessMsg(t('acceptSuccess'));
      await refresh();
    } catch (e: unknown) {
      if (isWildoBackendError(e)) throw e;
      setError(t('errorGeneric'));
    } finally {
      setBusyId(null);
    }
  },
  [refresh, refreshOrganizations, t],
);

The service checks that the addressed pending membership belongs to the current user. Public token-based acceptance and authenticated acceptance converge on membership activation, but the latter does not issue a replacement session. A custom invitation inbox should use these ownership-checked operations rather than accepting an arbitrary membership identifier through an administrative update.

Revoking or rejecting an invitation withdraws the pending membership. An unusable public invitation produces a common refusal rather than exposing whether another person’s invitation exists.

Enable continuity for the destination account

Set anonymousSessionsEnabled: true in the destination user type’s authentication policy, as Wonder Todos does for its member accounts. This is checked again by transposeOwnership: a resource’s anonymous settings alone do not authorize conversion into every account type.

Opt the resource into anonymous ownership

Wonder Todos’ draft-note resource declares the policy alongside its schema and operations. Selected configuration from draft-notes.resources-config.ts:

mainSchema: DraftNotes_Schema,
resourceIdentifier: TasksManager_ResourceType.DRAFT_NOTES,
resourceFieldIdentifier: TasksManager_ResourceFieldIdentifier[TasksManager_ResourceType.DRAFT_NOTES],
resourceRelationships: resourcesRelationships,
isSystemResource: false,
isAnonymizable: true,
transpositionPolicy: ResourceTranspositionPolicy.ADD,
systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },

Its create/read/list/update variants admit both CORE_APP_ROLES.APP_ANONYMOUS and CORE_APP_ROLES.APP_USER. The resource must use the supported user-self ownership scope; an anonymous identity does not become organization membership.

Decide how conversion treats existing records

These are data-lifecycle choices, not display preferences. Use replacement only when that is what the application means.

Hand off the server-recognized session

The authentication controller passes the recognized anonymous identity into transposeOwnership after conversion. The server updates ownership and records the result; the browser does not prove ownership by submitting an arbitrary user identifier. Incomplete resource moves are tracked and retried by reconciliation, so conversion is not modeled as an all-or-nothing copy in frontend state.

Reconciliation deliberately does not repeat REPLACE deletion: the account may have gained new records since conversion. If the initial deletion failed, retry can leave both the account’s existing records and the moved anonymous records. This preserves subsequent work rather than deleting it to recreate the original replacement outcome.

For website-to-application continuity, configure the actual cookie and deployment topology and initialize non-essential sessions according to the application’s consent policy. The anonymous-session mechanism supplies continuity; it does not replace authentication or consent.

Store the identity relationship, not another user

The identity-link record connects the local userId to a provider reference and provider subject, with the relevant connection/scope context. Social and enterprise provisioning create or resolve those links as part of their own verified sign-in flows.

An external identity link is not an outbound connected-account credential for calling a vendor API. It answers who is signing in, not whose third-party token an integration spends.

Keep removal on the authenticated owner’s path

AuthMethodManagementBackendService.unlinkIdentityLink and passkey removal share one transaction-owning guard. It enforces removal policy, serializes removals on the account’s credential record, removes the exact owned target, then evaluates the state that would remain. If no established first factor survives, the transaction rolls back.

This excerpt is the decision inside that transaction. remove performs the specific identity-link or passkey mutation; every participant receives the same transaction options.

const locked = await this.repositoriesRegistryHandler.atomicGuardedMutation<UserCredentials>(
  CoreResourceType.USER_CREDENTIALS,
  { _id: credentials._id, userId },
  { increment: { _version_db_doc: 1 } },
  ec,
  options,
);
if (!locked) throw this.errorBuilder.buildError(ErrorType.CONFLICT, ec, {
  context: { reason: 'Credential record changed during removal' },
});
await this.enforceUserMethodRemovalAllowed(ec, userId, options);
const result = await remove(options);
await this.authMethodSurvival.assertSurvivingFirstFactor(ec, userId, options, frontendServiceName);
return result;

A stored password counts only when enabled. Enrolled passkeys, supported passwordless routes and established external sign-in routes are evaluated against their current policy and configuration. A SCIM provisioning record or a TOTP second factor does not replace a first factor. The guard also does not assume that a provider will recreate a deleted link through email matching later.

The credential version used for serialization is separate from the user’s authorization version, so the guard does not revoke sessions merely to coordinate removals. A missing link and another person’s link both produce not-found. The success audit follows the committed removal.

This protects established first-factor routes; it does not guarantee message delivery, provider availability, completion of MFA or administrator recovery. Stored-method inventory remains available separately from this safety decision.

Preserve the provider’s verified identity

Do not create links by trusting an email string supplied by a browser. Provider callbacks own subject verification and any permitted email-based linking. Removing a local link does not delete the external provider account, delete the application user or automatically change organization membership. Your interface should name the action as removing a sign-in method.

Enable availability, then configure the customer

Wonder Todos declares scimProvisioning: { enabled: true } under organizationTypes.workspace in backend-api/src/saas-config.backend.ts. That makes the route available for the type; it does not mean every organization already has an active directory connection.

The organization has its own provisioning configuration and bearer token. The endpoint path is exposed as scimEndpointUrl, derived from the actual API base rather than stored as tenant data. Combine it with the deployed API host when configuring the directory.

Save the customer’s provisioning policy

Keep scimProvisioning: { enabled: true } alongside the existing organization type’s membership and creation rules. The backend mounts the directory routes when at least one type enables them, and checks the token’s organization type again on incoming requests. Also enable CoreFeature.DIRECTORY_PROVISIONING for the target organization through the application’s feature configuration; the type-level switch does not grant that customer feature.

In an application-owned, organization-admin-authorized backend operation, use the registered configuration service. This helper receives the backend container and the caller’s execution context from that operation; organizationId is its authorized target organization:

import {
  AuthOrganizationConfigurationService,
  SAAS_SERVICE_TYPES,
  type ExecutionContext,
  type InversifyContainer,
} from '@wildo-ai/saas-backend-lib';
import { AuthScopeType, CORE_ORG_ROLES } from '@wildo-ai/saas-models';

async function configureDirectory(
  container: InversifyContainer,
  executionContext: ExecutionContext<any>,
  organizationId: string,
): Promise<void> {
  const configuration = container.get<AuthOrganizationConfigurationService>(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService);
  await configuration.saveScimProvisioningConfig(
    executionContext,
    AuthScopeType.ORGANIZATION,
    organizationId,
    { autoCreateUsers: true, autoVerifyEmail: true, autoDeactivateUsers: true, defaultRole: CORE_ORG_ROLES.ORG_MEMBER },
  );
}

The service is already registered by the engine. It creates or updates the scope’s configuration through the services registry with the caller’s context, preserving authorization and audit attribution. This is a backend integration helper, not a new HTTP route: the configuration resource’s create/update operations are internal. Keep the administration action in your application’s declared operation and access policy.

Here, directory assertions may create accounts, verify their email and withdraw membership on deactivation. Choose those switches deliberately. The save service rejects the core owner/admin roles as defaultRole; custom roles still need an application-level review of the authority they grant.

Issue the directory its own credential

An organization administrator invokes ScimTokens_Operations.GENERATE_TOKEN on CoreResourceType.ORGANIZATION_SCIM_TOKENS. The registered API operation borrows CREATE, accepts displayName and an optional ISO expiresAt, and returns a persisted record with a one-time token. With BACKEND_URL set to the application’s API base (including its API prefix), invoke the organization-scoped operation with an administrator session. The directory credential itself is not the administrator’s session token:

curl --fail-with-body "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-scim-tokens/generate-token" \
  -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"displayName":"Company directory"}'

Add expiresAt with a future ISO timestamp when the deployment requires an expiry. Transfer the returned token to the directory’s secret configuration and retain the record ID for lifecycle management. Only its hash is stored. Rotation returns newToken and replaces the hash immediately; there is no old-token grace window. Revocation makes the record inactive and keeps it for audit.

Send a directory user and inspect the result

Set SCIM_BASE_URL to the deployed API host plus the configuration’s scimEndpointUrl, and SCIM_TOKEN to the one-time secret above. Use an email accepted by the customer’s verified-domain policy and a user type eligible to join that organization. This example uses a disposable account in your own test organization:

curl --fail-with-body "$SCIM_BASE_URL/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H 'Content-Type: application/scim+json' \
  --data-binary @directory-user.json

The directory-user.json payload supplies both the directory identifier and the profile fields used by the default mapping:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId": "directory-person-001",
  "userName": "person@your-verified-domain.example",
  "name": { "givenName": "Alex", "familyName": "Morgan" },
  "emails": [{ "value": "person@your-verified-domain.example", "primary": true }],
  "active": true
}

A successful create returns HTTP 201 with the SCIM user ID and a Location header. Read Users/<returned-id> with the same credential and inspect the organization membership in your application. The token selects the organization; adding another organization ID to this payload does not change the target. Existing accounts can be linked rather than duplicated. A directory push is not an SSO login and does not create a browser session.

Choose what incoming changes may do

Selected current fields from scim-provisioning-config.shared.schemas.ts:

autoCreateUsers: z.boolean().default(true).isSummaryField().isAuditEvidence(),
autoVerifyEmail: z.boolean().default(true),
autoDeactivateUsers: z.boolean().default(true).isAuditEvidence(),
defaultRole: z.string().optional().isAuditEvidence(),
attributeMapping: ScimAttributeMappingSchema.optional(),

defaultRole is an organization-wide role grant, so configuring it is an access decision. Unit assignments use separate organizationUnitMapping and defaultUnitRole fields. When both are configured, directory synchronization becomes authoritative over those assignments: a push replaces the mapped set, including removal of manual assignments. Leave that mapping absent when the application should own them manually.

Let the credential determine the tenant

The middleware hashes the presented bearer token, verifies active/expiry state and takes organizationId from its stored record. The caller cannot choose another organization in the body. Rate limits are per token, keeping one directory’s traffic from using another credential’s budget.

Match the supported provisioning surface

The controller exposes Users create/read/list/replace/patch/delete and bounded bulk operations. Ordinary and bulk writes share lifecycle and unit-update handlers: replacement synchronizes the full mapped unit state; PATCH changes only the supplied fields. Delete performs membership deactivation through provisioning policy.

The active response and filter describe membership state in the addressed organization. Reactivation uses current acquisition and default-role policy rather than restoring historical privileges, and cannot unlock a globally disabled account. Configuration read failures refuse mutation instead of substituting permissive defaults. Groups, sorting and entity tags are not supplied by this surface; configure the directory accordingly. Local first-factor credentials are neutralized for actively directory-managed users so directory removal cannot be bypassed by an old local sign-in method. SSO and provisioning share account creation services but remain distinct connections and responsibilities.

Use a lifecycle action rather than a status patch

An illustrative suspension request body is:

{
  "suspensionReason": "Account activity is under review",
  "notifyMembers": false
}

Submit it through organizations.suspend with the required platform authority and tenant reach. The action accepts ACTIVE or TRIAL; it refuses an already suspended organisation. The reason is required, and notifyMembers: false suppresses its member notification.

Understand what the transition changes

The transactional implementation sets the organisation to SUSPENDED, reconciles application user types granted by that organisation type and tied to membership through requiresOrgMembership.orgTypes. The paired organization/user-type declarations are prerequisites for that revocation: the organization type names what it grants, and the user type names the organization types whose membership it requires. Another qualifying active membership preserves the type. Without that membership requirement, this reconciliation does not remove the application user type; the suspended workspace still stops conferring organization-scoped authority. Tokens are invalidated when a type is actually revoked, rather than logging out every member unconditionally. Organisation-scoped authority is derived from the current organisation state, so retained membership rows do not keep conferring access.

Reactivation sets ACTIVE; it does not restore a remembered previous trial state. The activate operation accepts SUSPENDED or TRIAL_EXPIRED and re-grants organisation-derived user types.

Give recovery its own reach

Activation explicitly admits the platform cross-tenant administration path. A non-member platform operator still needs the applicable time-limited access grant for the target organisation. Suspension does not acquire that crossing merely because activation has it.

Both actions enforce their state conditions on the server as well as in the interface. Follow reversible deletion when the intended outcome is offboarding rather than a temporary pause.

Mark the organisation through its deletion request

Both the tenant-administrator and platform-operator variants of Organization_Lifecycle_Operations.REQUEST_DELETION (request_deletion) require fresh authentication proof. The standard interface requests that proof before submitting the operation; permission to administer the workspace alone is not enough.

The internal operation key is request_deletion; the generated HTTP path uses request-deletion. Choose the variant that matches the caller:

For the tenant-administrator path, the request is:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/request-deletion" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "x-reauth-token: $REAUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"The customer has asked to close this workspace"}'

REAUTH_TOKEN is the fresh proof returned by the application’s step-up authentication flow, for the same caller as ADMIN_TOKEN. It is not another name for the session token. The optional reason is limited to 500 characters. The operator variant uses the /admin suffix and also requires fresh proof; changing the URL does not grant platform authority or tenant reach.

The operation writes status: DELETED, deletionRequestedAt and purgeScheduledAt in the lifecycle transaction. It also reconciles assigned application user types granted by that organisation type and tied to membership through requiresOrgMembership.orgTypes. A type is retained while another qualifying active membership exists. Tokens are invalidated only when a type is actually revoked; closing the workspace separately removes its organisation-scoped authority.

Keep the deadline attached to this decision

The deadline is calculated from tenantTeardown.retentionWindowDays when the organisation is marked. Changing the configuration later does not rewrite deadlines already recorded. The warning belongs on this reversible mark, while someone can still ask for recovery. After marking, inspect all three stored values: DELETED, deletionRequestedAt and purgeScheduledAt. Repeating the mark on an already deleted organization is refused, so it cannot silently restart the recovery window.

Restore an existing marked organisation

restore requires platform authority and, for a non-member crossing, the appropriate access grant. It sets ACTIVE, clears both marks and re-grants organisation-derived user types. It does not restore a previous suspended or trial state.

An authorized platform operator restores the addressed organization with:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/restore" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"The closure request was withdrawn"}'

Arrange the target-organization access grant before using the cross-tenant path. After restoration, verify ACTIVE, cleared deletion timestamps and access through a qualifying membership. The reason is optional and limited to 500 characters.

The restoration gate tests that the row is marked, not whether its deadline has passed. Until purge actually removes the row, it can still be restored. Once the row is gone, addressing cannot find it. This makes the configured period a minimum recovery opportunity subject to the purge schedule, rather than a promise that removal happens at the exact deadline.

Configure the operator policy

In backend-api/src/saas-config.backend.ts, the optional tenantTeardown block accepts:

tenantTeardown: {
  retentionWindowDays: 30,
  purgeCronSchedule: '0 3 * * *',
  purgeBatchSize: 50,
},

These are the current defaults, including when the entire tenantTeardown block is omitted. Omitting it does not disable purge. Choose the period to match the application’s obligations. The schedule controls when due organisations are processed; it does not change their individual stored deadlines.

Follow the batch through normal deletion

Application startup registers the engine’s organisation-purge batch. It selects organisations with status: DELETED and an existing purgeScheduledAt earlier than the current instant, bounds the attempted set and invokes the route-less internal delete operation for each.

This reuses cascade and retention behavior instead of maintaining a second teardown algorithm. A child configured for retention and impersonalisation follows that policy; do not describe purge as unconditional physical deletion of every related business record.

Verify that scheduling reaches a running executor

Registration makes the batch available; it does not prove a scheduled run happened. The application’s cron registration must reach the crontabs manager, and the background execution path must have its queue connection and consumers running. Startup can continue when queue initialization or cron synchronization has failed, so a healthy HTTP endpoint alone is not proof that cleanup is operating.

Check the registered organization-purge schedule, then a completed run and its result. Compare the stored deadline with the actual execution time; an organization becomes eligible after its deadline, and removal occurs when a successful run reaches it. Do not rewrite stored deadlines merely to clear a backlog.

Operate failures and backlog explicitly

The result distinguishes attempted, purged and failed organisations. dueOrganizations is the number attempted in this bounded run, not the total backlog; purged and failed describe those attempts. A failure is logged with the organisation and deadline; the next eligible run can attempt it again. A run bounded by batch size also logs that more work may remain.

The organisation deletion audit hook runs on this internal delete path as well as the administrator path. Its evidence records the organisation from the pre-deletion snapshot, which remains meaningful after the live row has disappeared.

Read the operation requirement independently of risk labels

The administrator delete variant declares requiresStepUpAuthentication: true. This is the operative requirement; a risk label alone is not equivalent.

The following excerpt shows the security-relevant contract, with surrounding operation configuration omitted:

{
  roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
  riskLevel: ResourceOperationRiskLevel.HIGH,
  requiresStepUpAuthentication: true,
}

Use the generated administrator delete operation and its re-authentication flow. The service handler checks the per-operation requirement rather than accepting an old login merely because it is still a valid session.

Address the administrator variant explicitly

The HTTP operation is DELETE /organizations/{organizationId}/admin. The default DELETE variant is internal and route-less; it is what the scheduled purge uses. There is no ordinary tenant-facing delete route to use instead.

For a platform super-administrator who also has legitimate scope access to the target workspace:

curl -X DELETE "$BACKEND_URL/organizations/$ORG_ID/admin" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "x-reauth-token: $REAUTH_TOKEN"

Obtain REAUTH_TOKEN from the application’s step-up flow for that same authenticated caller. The fresh proof accompanies the request as x-reauth-token; a still-valid login token by itself does not satisfy the operation. This route performs the purge immediately rather than setting a future deadline.

Keep tenant reach as a separate check

This irreversible door does not declare cross-tenant platform administration. A non-member operator cannot infer permission from the role or from a recovery grant used by a different operation. A successful fresh identity check proves the caller again; it does not manufacture tenant access.

Preserve a meaningful deletion record

The deletion audit implementation captures the organisation’s identity before removal and emits after the delete. Both the administrator variant and the scheduled internal deletion variant register the hook.

Verify the refused cross-tenant request, the missing-step-up request and the allowed deletion separately. Only the last should remove the row. For ordinary customer offboarding, request deletion keeps the recovery interval available.

Count authority, not the text of one role

A usable owner combines a usable membership, a usable linked user and a role that confers ORG_OWNER through the current role hierarchy. A role label on an invited or inactive membership does not satisfy the floor.

Let the existing membership operation enforce it

The create/update/removal implementations call the owner-floor authority as appropriate. Application code should use the normal membership service path rather than editing the repository to bypass it.

The guard measures the owners the proposed change would remove. This selected excerpt from organization-owner-floor.backend.utils.ts runs after the transaction has established the serialization boundary; intervening comments are omitted:

const usableOwnerMemberIds = await measureUsableOrganizationOwners(params);
const reducedMemberIdSet = new Set(reducedMemberIds.map((memberId) => String(memberId)));
const reducedUsableMemberIds = usableOwnerMemberIds.filter((memberId) => reducedMemberIdSet.has(memberId));
if (reducedUsableMemberIds.length === 0) return undefined;

const remainingUsableOwners = usableOwnerMemberIds.length - reducedUsableMemberIds.length;
if (remainingUsableOwners >= ORGANIZATION_OWNER_FLOOR_MINIMUM) return undefined;

return { organizationId, reducedMemberIds: reducedUsableMemberIds, remainingUsableOwners };

An empty result means this change does not breach the floor. A returned breach identifies the affected organisation and reductions for the caller’s refusal; it is not permission to proceed.

The guard serialises competing reductions on the organisation record inside the transaction. Two removals that each observe a second owner must not both commit and leave zero. This is why a separate preflight count in a custom UI is only guidance, not enforcement.

Give the refusal an actionable recovery path

A refused reduction returns HTTP 409, with error.code set to LAST_ORGANIZATION_OWNER in the HTTP response. Use the public enum to distinguish it from an unrelated conflict. For example, this application-owned predicate can select the ownership-transfer message in a custom administration screen:

import { AdministrativeContinuityErrorCode } from '@wildo-ai/saas-models';

export function needsAnotherOrganizationOwner(
  status: number,
  errorCode: unknown,
): boolean {
  return (
    status === 409 &&
    errorCode === AdministrativeContinuityErrorCode.LAST_ORGANIZATION_OWNER
  );
}

Pass the HTTP status and the parsed response’s error.code; keep the normal handling for other failures. Do not match the human-readable message or the internal audit reason. This conflict needs a change in ownership, so automatically retrying the same request is not a remedy.

Guide the administrator to give an active organization-wide member an owner-conferring role, confirm that member’s linked account is active, and then retry the original operation. Preserve the target member’s other required roles when updating their role set. A pending owner invitation is insufficient until accepted. An owner grant on an organization unit is also insufficient: the floor measures organization-wide memberships, not unit assignments.

The server still evaluates the final write in its transaction. A UI that shows a second owner is helpful guidance, not proof that concurrent changes cannot alter the result.

Keep distinct decisions distinct

Platform user deactivation can stop a compromised account even when that strands an organisation; the affected organisation is reported for repair. An explicit subject-erasure decision has its own acknowledged-breach path. Neither should be described as an ordinary membership administrator’s permission to remove the final owner.

If the organisation is already stranded, use the ownership recovery operation. It promotes a usable existing member; it does not weaken the regular floor.

Establish the target before invoking recovery

The target must have both a usable organisation membership and a usable user account. An invitation or disabled account cannot become a functioning owner merely by receiving another role.

The operation is organizationMembers.grantOwnership. Its request requires a justification:

{
  "justification": "Restore customer administration after the former owner left"
}

A non-member caller needs application-level super-administrator authority and the applicable target-organisation access grant. The operation explicitly admits this crossing; ordinary membership operations do not inherit it.

Invoke the repair on the membership

First complete the temporary-access request and approval sequence. For a genuinely ownerless organization, the request handler can establish the recorded recovery grant without waiting for the missing owner. An operator still needs the required platform role and a usable grant.

MEMBERSHIP_ID below identifies the existing organization-member row, not the global user. Obtain that identifier from the authorized support context; the grant does not make an ordinary cross-tenant membership LIST available. This route is the one exercised by Wonder Todos’ ownership-repair example:

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/organization-members/$MEMBERSHIP_ID/grant-ownership" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"justification":"Restore customer administration for support case SUP-42"}'

Use the operator’s own authenticated token after the grant becomes usable. The request does not accept a replacement role array. On success, the existing member gains ownership while retaining their other roles; the customer can resume administration. Retrying for an existing owner does not duplicate authority.

Understand the authoritative result

The prefix marks roles authoritative. It checks the current membership and user, retains all existing roles and adds ORG_OWNER if they do not already confer ownership. A retry is idempotent: a member who is already an owner remains an owner.

It cannot demote someone, move the membership or replace the entire role set with values supplied by the caller. The write and the linked-user usability check participate in the same transaction.

Confirm the repair and preserve the operator’s reason

Re-check that the target can administer the workspace and appoint another owner where appropriate. The current request contract requires justification, but the implementation does not persist that request value; keep the operator’s reason in the operational case record. The emitted operation evidence must not be described as containing the discarded justification.

Connect operation, target and template

The restore declaration includes this actual notification definition:

userNotifications: [
  {
    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
    channel: CoreUserNotificationChannel.EMAIL,
  }
]

It tells the notification pipeline whom the event is for and which channel to use. The application supplies the corresponding email template and delivery configuration. Wonder Todos keeps those templates under backend-api/src/engine/email/resources/organizations/, including separate templates where the administrator variant has a distinct reference.

Register the file under the reference the operation resolves

For restore, the operation identifier is Organization_Lifecycle_Operations.RESTORE (restore), the target is ORGANIZATION_USERS, and the resolved template reference is email.organizations.restore.organization-users. Wonder Todos supplies it from:

backend-api/src/engine/email/resources/organizations/
  restore.organization-users/
    template.tsx
    labels.en.ts

template.tsx default-exports an EmailTemplateDefinition; each locale file exports labels. The normal compiler must publish the corresponding JavaScript files before the startup scanner can load them. A source file alone is not a registered runtime template.

This is the resource-directory scan used by the existing email definitions module, with its shared options inlined:

import {
  scanEmailTemplateDirectory,
  type EmailTemplateDefinition,
} from '@wildo-ai/saas-backend-lib';

const resourceTemplates = await scanEmailTemplateDirectory<EmailTemplateDefinition>({
  importMetaUrl: import.meta.url,
  subdir: 'resources',
  keyFromPath: (relativePath) => `email.${relativePath.replace(/\//g, '.')}`,
});

Keep this scanner in backend-api/src/engine/email/email-template-definitions.ts, where resources is a sibling directory. Its map is merged into the existing emailTemplateDefinitions, alongside system templates. The engine backend module contributes that map through its emailTemplateDefinitions property; modules-registry.backend.ts collects those module maps as defaultEmailTemplateDefinitions for buildApplicationInitializationConfigFromModules. Extend this existing path rather than creating a second registry or importing the template directly in a sender.

The HTTP route uses request-deletion, but the template reference retains the internal request_deletion identifier. The variant segment also matters: a template for the tenant action does not satisfy the administrator action’s reference.

Match the message to the transition

Organization_Lifecycle_Operations.REQUEST_DELETION (request_deletion) carries the warning at the reversible mark. restore informs members when access returns. Suspension’s condition respects notifyMembers; activation targets the administrative audience. These audiences are intentional and should not all become the same generic broadcast.

Organisation category email routing can replace the member audience for mapped categories. An ORGANIZATION_USERS target remains a per-member audience, as described in workspace email settings.

Verify delivery prerequisites as well as the declaration

The startup validator reports unresolved template references and names the directory expected. That check does not itself prove an email was delivered. Exercise the operation with the configured email transport and inspect its delivery result, especially the quiet-suspension case and the deletion-request warning.

An organization administrator creates the credential through the organization API-key resource. Supply a recognizable name, the roles the integration needs and an optional expiry. The requested roles must fall within the caller’s grant ceiling. The organization-scoped route selects the account; application keys use their separate application resource.

The creation response includes plainKey once, alongside the key record. Save that value in the integration’s credential store before leaving the creation step. For an organization integration, it starts with sk_org_; the application variant uses sk_app_.

Set RESOURCE_URL to an allowed endpoint within that key’s scope and API_KEY to the returned plainKey. This is the request contract declared in api-keys.shared.schemas.ts and exercised by external-access-auth.e2e.ts:

curl "$RESOURCE_URL" \
  -H "Authorization: $API_KEY"

The header contains the raw key, without a Bearer prefix. The backend resolves its machine principal, scope and roles before authorizing the requested operation. A successfully authenticated key can still receive an authorization refusal when its role or tenant does not match the operation.

Keep the secret and the authority separate

The API-key create handler checks the requested roles, creates secret material and lets the normal resource path persist the hash. Its response adds the plaintext key once:

This implementation excerpt from api-keys.custom-impl.backend.service.ts shows the decision in context; explanatory source comments are omitted.

export function buildApiKeyMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): ApiKeyImplHandlers {
  return {
    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);
      const { plainKey, keyPrefix, hashedKey } = generateApiKeyMaterial(scope);
      PLAINTEXT_KEY_BY_EC.set(executionContext, plainKey);
      return { ...(input as Record<string, unknown>), keyPrefix, hashedKey };
    },
    postfixCoreOperations: async (_id, createdKey, executionContext, _operationPath, _utils) => {
      if (!createdKey || typeof createdKey !== 'object') return createdKey;
      const plainKey = PLAINTEXT_KEY_BY_EC.get(executionContext);
      PLAINTEXT_KEY_BY_EC.delete(executionContext);
      if (!plainKey) return createdKey;
      return { ...(createdKey as Record<string, unknown>), plainKey };
    },
  };
}

Store the one-time result in the integration

Capture plainKey from the creation response and place it in the integration’s credential store. Subsequent resource reads do not recover the plaintext value. The authenticated request resolves the key’s organization or application and the roles assigned at creation.

Choose rotation when you need the old secret to stop working at a known time. Regeneration is not the same retirement policy.

Rotate with fresh proof and an explicit cutoff

For the default organization-key ROTATE operation, the caller needs ORG_ADMIN and a single-use reauthentication proof. A recently established session alone does not satisfy the operation’s explicit step-up requirement. Application-level administration uses its separately authorized variant; do not substitute that route for an organization administrator’s call.

This illustrative JavaScript runs in a trusted first-party administration client. reauthUrl is the application’s /auth/reauth API endpoint; rotateUrl is the selected key’s default ROTATE URL from its generated operation contract. sessionToken belongs to the administrator, not to the integration whose key is being replaced. This example uses a locally enrolled password accepted by the effective step-up policy; the standard interface handles other supported factors.

async function rotateIntegrationKey({ reauthUrl, rotateUrl, sessionToken, password, cutoff }) {
  const json = async (response) => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const body = await response.json();
    return body.data ?? body;
  };
  const headers = { authorization: `Bearer ${sessionToken}`, 'content-type': 'application/json' };
  const proof = await json(await fetch(reauthUrl, {
    method: 'POST', headers,
    body: JSON.stringify({ method: 'PASSWORD', password }),
  }));
  if (!proof.reAuthToken) throw new Error('Reauthentication returned no operation proof');

  const replacement = await json(await fetch(rotateUrl, {
    method: 'PUT',
    headers: { ...headers, 'x-reauth-token': proof.reAuthToken },
    body: JSON.stringify({ oldKeyInvalidationDate: cutoff.toISOString() }),
  }));
  if (!replacement.plainKey) {
    throw new Error('Rotation returned no replacement secret');
  }

  // Hand this directly to the integration's credential store, not a log.
  return {
    plainKey: replacement.plainKey,
    oldKeyId: replacement.oldKeyId,
    oldKeyInvalidationDate: replacement.oldKeyInvalidationDate,
  };
}

Choose a future cutoff that leaves time to distribute and verify the replacement. Omitting oldKeyInvalidationDate defaults to immediate retirement, not a grace period. Save the returned plainKey once, switch the integration, verify a real permitted request with the new raw key, then verify the prior value is refused after the returned cutoff. Subsequent reads cannot recover the secret.

The proof is short-lived and single-use. A retry may require a new proof; if the rotation response was lost, investigate the key state before blindly rotating again. REGENERATE deliberately has different semantics: it keeps the prior secret without a scheduled cutoff and does not carry the same explicit rotation step-up gate. Neither operation grants new roles.

Keep role changes out of secret maintenance

These resources do not expose an ordinary roles-changing update. Their lifecycle handlers accept their own inputs and do not use rotation as a second path to grant authority. If the integration needs different responsibilities, provision the appropriate credential rather than treating a secret replacement as a permissions change.

Create the organization or application OAuth client through its resource operation. Set its allowed grants and roles, retain the one-time plainSecret, then use the token endpoint. A client using client_credentials acts as itself.

The token issuer carries the resolved scope and principal into the signed claim:

This implementation excerpt from machine-token-issuer.backend.service.ts shows the decision in context; explanatory source comments are omitted.

public async issueClientAccessToken(request: MachineAccessTokenRequest): Promise<MachineAccessTokenResponse> {
    const maxMinutes = this.appConfigService.config.jwt.accessTokenExpirationMinutes;
    const requestedMinutes = request.expiresInMinutes ?? maxMinutes;
    const minutes = Math.max(1, Math.min(requestedMinutes, maxMinutes));

    const claim: Jwt_MachineToken_CreationParameter = {
      type: request.scopeType === ResourcePrimaryScope.ORGANIZATIONS
        ? ExecutionContext_ExecutionType.ORGANIZATION_MACHINE
        : ExecutionContext_ExecutionType.APPLICATION_MACHINE,
      clientId: request.clientId,
      scopeId: request.scopeId,
      roles: request.roles,
    };

    const accessToken = await this.jwtService.createJwtForMachineToken(claim, {
      audience: request.audience,
      expiresInMinutes: minutes,
    });

    this.logger.debug('Issued machine client-credentials access token', {
      clientId: request.clientId,
      scopeType: request.scopeType,
      scopeId: request.scopeId,
      audience: request.audience,
      expiresInMinutes: minutes,
    });

    return { accessToken, tokenType: 'Bearer', expiresIn: minutes * 60 };
  }

Request the intended resource

The token request names grant_type=client_credentials, the client credential and the resource audience. Present the returned access_token as a Bearer credential to that resource. The token endpoint checks that this client allows the grant and that the requested resource is known.

The public token endpoint uses the application’s configured access-token lifetime. It does not accept a requested lifetime. The expiresInMinutes option shown above belongs to the internal issuer API; its callers may shorten the policy maximum.

The following request follows external-access-auth.e2e.ts. Set BACKEND_URL to the application backend, CLIENT_SECRET to the one-time secret and RESOURCE_AUDIENCE to a resource identifier advertised by that deployment.

curl "$BACKEND_URL/oauth/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "resource=$RESOURCE_AUDIENCE"

The response supplies access_token, token_type and expires_in. Save access_token as ACCESS_TOKEN; set RESOURCE_URL to an endpoint in that audience for which the client has permission:

curl "$RESOURCE_URL" -H "Authorization: Bearer $ACCESS_TOKEN"

An audience match is necessary but does not grant an operation role. A valid organization client still cannot use its token to operate on another organization’s records.

Separate the client secret from tokens already issued

The client secret is used to obtain tokens. A Bearer token is a signed snapshot of the client’s roles and scope with its own expiry. Changing the first does not rewrite the second.

There is no dedicated OAuth-client deactivate/reactivate operation pair in this resource contract. The status row above describes an admission condition, not an extra management endpoint.

Rotation and regeneration update the same client record; the returned plainSecret is the one-time value to install in the integration. Regeneration is therefore not an immediate retirement of the previous secret. Choose rotation with a deliberate cutoff when the outgoing secret must stop obtaining tokens.

The ordinary API and supported external machine-token paths verify the signature, issuer, audience and token expiry, then construct machine authority from the claims. They do not look up the client again in those Bearer branches. Operation authorization and scope checks still apply; this is not a promise that every request succeeds until expiry.

Direct authentication with the OAuth client secret is different: that path reads the client and checks its status and expiry for the request. User-delegated agent tokens also follow a different validation path. Do not extend this machine-Bearer behavior to every kind of credential.

Make the cutover observable

Use the application’s configured access-token lifetime and the token response’s expires_in when planning the overlap. The public token endpoint does not accept a shorter lifetime requested by the integrating service.

For a controlled rotation, keep a pre-rotation token and test these separate outcomes in a disposable integration:

1. Obtain a new token with the replacement secret and call an operation the client is allowed to use.
2. After the chosen cutoff, confirm the old secret can no longer obtain a token.
3. Check the pre-rotation Bearer separately: the secret cutoff does not itself revoke that token. Token expiry and the resource’s other authorization checks remain its boundaries.
4. Confirm the same token is refused after expiry. Keep an authorized fresh-token call as a control so a missing route or stopped service is not mistaken for revocation.

These checks distinguish a successful secret replacement from withdrawal of already issued access. If the product requires immediate client-wide invalidation of machine Bearers, the current authentication paths do not supply that guarantee.

Design business code for a machine caller

Machine identity is recorded independently from user identity. A machine-created record may have no creator user ID, so custom business logic should use the execution context’s principal rather than assuming every authorized action has a human userId.

User delegation is a separate flow: agent tokens represent a consenting person, while this client represents the service itself.

Discovery publishes the browser-facing consent URL, token endpoint, supported grants and signing-key information. The browser-facing authorization flow uses a registered redirect URI, state, a PKCE S256 challenge and the intended resource.

At exchange, the provider verifies the code against the original client, redirect and verifier before issuing anything:

This implementation excerpt from oauth-provider-token.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const grant = await authCodeService.exchangeAuthorizationCode({
      code: request.code,
      clientId: request.clientId,
      redirectUri: request.redirectUri,
      codeVerifier: request.codeVerifier,
      presentedClientSecret: request.clientSecret,
    });

Build a public client’s authorization request

Use a registered public client with authorization-code access, an exact registered callback URI and an allowed MCP or A2A resource audience. Public registration uses PKCE rather than a client secret. A confidential client additionally authenticates at token exchange; do not place that secret in browser JavaScript.

This illustrative browser client uses metadata from a trusted, configured discovery URL. The browser must return to the same client origin/tab so its pending state remains available. A production client can use an OAuth library for this protocol bookkeeping; these functions expose the values that must stay connected.

async function beginDelegation({ discoveryUrl, clientId, redirectUri, resource }) {
  const response = await fetch(discoveryUrl);
  if (!response.ok) throw new Error(`Discovery HTTP ${response.status}`);
  const metadata = await response.json();
  const base64url = (bytes) => btoa(String.fromCharCode(...bytes))
    .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const challenge = base64url(new Uint8Array(await crypto.subtle.digest(
    'SHA-256', new TextEncoder().encode(verifier),
  )));
  const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
  sessionStorage.setItem('wildo-delegation', JSON.stringify({
    state, verifier, clientId, redirectUri, resource,
    tokenEndpoint: metadata.token_endpoint,
  }));

  const authorize = new URL(metadata.authorization_endpoint);
  authorize.search = new URLSearchParams({
    response_type: 'code', client_id: clientId,
    redirect_uri: redirectUri, scope: 'openid', state,
    code_challenge: challenge, code_challenge_method: 'S256',
    resource,
  }).toString();
  window.location.assign(authorize.href);
}

The discovered authorization endpoint is the frontend consent page. Wildo handles login and the person’s decision there. Its authenticated backend authorization/decision calls return JSON containing redirect_to; the frontend navigates to it. Your external client receives the callback, not the first-party session token or the internal consent token. Denial returns an error rather than a usable code. Consent may be bypassed only where the provider’s client/user policy permits it.

Validate the callback before exchanging its code

Run this on the registered callback page. This compact example allows one outstanding authorization attempt per tab; starting another replaces the pending attempt. It removes the pending entry before exchange, so a failed exchange starts a new authorization rather than replaying the code indefinitely.

async function finishDelegation() {
  const saved = sessionStorage.getItem('wildo-delegation');
  if (!saved) throw new Error('No pending authorization');
  const pending = JSON.parse(saved);
  const callback = new URL(window.location.href);
  const expected = new URL(pending.redirectUri);
  if (callback.origin !== expected.origin || callback.pathname !== expected.pathname
      || callback.searchParams.get('state') !== pending.state) {
    throw new Error('Authorization callback does not match the pending request');
  }
  sessionStorage.removeItem('wildo-delegation');
  if (callback.searchParams.has('error')) throw new Error('Authorization was not granted');
  const code = callback.searchParams.get('code');
  if (!code) throw new Error('Authorization returned no code');

  const response = await fetch(pending.tokenEndpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code', client_id: pending.clientId,
      redirect_uri: pending.redirectUri, code, code_verifier: pending.verifier,
      resource: pending.resource,
    }),
  });
  if (!response.ok) throw new Error(`Token exchange HTTP ${response.status}`);
  const token = await response.json();
  if (!token.access_token) throw new Error('Token exchange returned no access token');
  return { accessToken: token.access_token, expiresIn: token.expires_in, resource: pending.resource };
}

The token request reuses the original redirect URI and verifier. Its resource echo is optional in the server contract, but must match when supplied; the authorization code already binds the audience. Keep the returned access token in the client’s appropriate credential/session handling, out of URLs and logs. Call only the returned intended resource using the delegated agent-request example.

Keep the grant families distinct

Authorization-code delegation does not issue an unrestricted first-party API session or a refresh token. It requires a valid agent resource audience. Identity scopes such as openid, email and profile control identity claims; they do not grant business operations.

Complete the browser handoff correctly

The frontend consent route is the browser authorization endpoint. The authenticated backend authorize call returns JSON containing redirect_to; the frontend navigates after receiving it. This avoids trying to follow a cross-origin client redirect inside an authenticated XHR.

Use interactive consent for the person’s decision, and machine clients when no person is delegating.

Configure auth.dynamicClientRegistration. It is disabled by default; when disabled the endpoint returns 404 and discovery does not advertise it. The default limit is ten registrations per source IP per hour.

In the backend-authored application’s auth section, enable the public door and choose a rate ceiling. These are the fields declared by DynamicClientRegistrationConfigSchema:

dynamicClientRegistration: {
  enabled: true,
  maxRegistrationsPerHourPerIp: 10,
},

The public endpoint checks that an incoming registration is not asking to grant itself business roles:

This implementation excerpt from oauth-provider-controller.backend.service.ts shows the decision in context; explanatory source comments are omitted.

if (body.roles !== undefined) {
      this.sendRegistrationError(res, 'invalid_client_metadata', 'roles cannot be requested at dynamic registration');
      return;
    }
    const requestedScopes = typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : [];
    const beyondIdentity = requestedScopes.filter((scope) => !OIDC_SUPPORTED_IDENTITY_SCOPES.includes(scope));
    if (beyondIdentity.length > 0) {
      this.sendRegistrationError(res, 'invalid_client_metadata', `scope(s) not available to a dynamically registered client: ${beyondIdentity.join(', ')}`);
      return;
    }

Register a public authorization-code client

Send the tool’s client_name and non-empty redirect_uris to /oauth/register. Redirects must pass the safe-URI policy: HTTPS, or permitted loopback HTTP, without embedded credentials or fragments. The returned client metadata describes what was actually registered.

For example, a tool can register the following illustrative HTTPS callback. Replace the example URL with the tool’s actual callback and BACKEND_URL with the application’s backend:

curl "$BACKEND_URL/oauth/register" \
  -H 'Content-Type: application/json' \
  --data '{
    "client_name": "Customer workspace tool",
    "redirect_uris": ["https://tool.example/callback"],
    "grant_types": ["authorization_code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email"
  }'

A successful response is HTTP 201 with client_id and the accepted metadata. It also returns a one-time registration_access_token and registration_client_uri for managing that registration. Store them securely: the management token is distinct from an OAuth client secret and does not authorize business API calls.

No OAuth client secret is returned. The tool uses client_id to start authorization with PKCE and user consent; it acts for that person rather than as an independently privileged machine.

Choose the onboarding policy for your audience

Enable this for clients that need the registration mechanism. Client metadata documents provide another identity-onboarding path. Neither mechanism bypasses consent, resource-audience checks or the person’s operation permissions.

auth.cimd selects DISABLED, ALLOWLIST or OPEN through CimdTrustPolicy. Disabled is the default. An allowlist entry can be the exact client URL or a bare host; the full URL is the narrower choice.

Import CimdTrustPolicy from @wildo-ai/saas-backend-lib. In the backend-authored application’s auth section, an exact-URL allowlist looks like this. The example hostname is illustrative; use the tool’s real HTTPS document URL.

cimd: {
  policy: CimdTrustPolicy.ALLOWLIST,
  allowedClients: ['https://tool.example/client.json'],
},

This uses the same configuration surface as Wonder Todos’ saas-config.backend.ts, with a narrowly selected client URL.

Publish a matching client document

The document supplies client_id, client_name and redirect_uris. Its client_id must equal the URL being resolved. The redirect used by authorization must exactly match a registered redirect, rather than merely share an origin or path prefix.

For the URL allowed above, serve JSON with a matching identity:

{
  "client_id": "https://tool.example/client.json",
  "client_name": "Customer workspace tool",
  "redirect_uris": ["https://tool.example/callback"],
  "token_endpoint_auth_method": "none"
}

The tool sends that full metadata URL as client_id on its authorization request, together with its redirect URI, state, PKCE challenge, identity scopes and target resource. Wildo resolves the document, checks the chosen redirect and continues to the user’s authorization step. Publishing this file does not itself create a token or a machine role.

The resolver applies URL and outbound-target checks even for allowlisted clients. It bounds fetch duration and size, validates the response and caches documents within a bounded lifetime. A metadata change is therefore not an instantaneous withdrawal of all previously fetched metadata.

Use the authentication mode the provider accepts

This implementation accepts the public-client none token-endpoint authentication method for metadata-document clients. It rejects unsupported authentication methods rather than silently treating a client claiming private-key authentication as public.

Published identity does not grant business authority. The tool still uses PKCE and user consent, then receives an audience-bound delegated token. Choose registered machine clients when the service should act under its own roles.

The backend creates a single-use consent-request token containing the authorization details. The frontend sends the decision using that token; the client does not get to replace the destination or scopes in a second request. This is the decision callback in Auth_OAuthConsent:

This implementation excerpt from Auth_OAuthConsent.tsx shows the decision in context; explanatory source comments are omitted.

const decide = useCallback(
    async (decision: 'approve' | 'deny') => {
      if (!consent || submittingRef.current) return;
      submittingRef.current = true;
      setStatus('submitting');
      setErrorLabel(null);
      try {
        const { redirect_to } = await getManualCallsHttpClient().oauthConsentDecision(
          consent.consent_token,
          decision,
          decision === 'approve' && remember,
        );
        window.location.assign(redirect_to);
      } catch {
        submittingRef.current = false;
        setStatus('error');
        setErrorLabel(UserOAuthConsentLabel.ERROR_DECISION);
      }
    },
    [consent, remember],
  );

Distinguish a trusted client from a user-approved client

A registered client configured not to prompt can skip consent only within its trust boundary. An organization client does not silently gain the same treatment for users outside that organization. A membership lookup failure forces the prompt.

Self-registered and metadata-document clients cannot declare themselves trusted. They still need the person’s authorization and the permitted code flow.

Remember only an affirmative choice

The remember control starts off. An approval with that choice can create a remembered grant; denying does not store an approval. The grant avoids an unnecessary future prompt only when it covers the same user, client, target and requested identity scopes.

Consent authorizes the handoff, not every business action. The endpoint continues checking the person’s actual permissions when a tool uses the resulting token.

The lookup is keyed by user, client and resource. Only an unexpired grant covering every requested scope returns true; a failed read returns false so the person is asked again:

This implementation excerpt from oidc-authorization-code.backend.service.ts shows the decision in context; explanatory source comments are omitted.

public async hasCoveringConsentGrant(userId: string, clientId: string, resource: string | undefined, requestedScopes: string[]): Promise<boolean> {
    try {
      const grant = await this.readConsentGrant(userId, clientId, resource);
      if (!grant) return false;
      if (grant.expiresAt && new Date(grant.expiresAt).getTime() <= Date.now()) return false;
      const granted = new Set(grant.scopes ?? []);
      return requestedScopes.every((s) => granted.has(s));
    } catch {
      return false;
    }
  }

Keep the target in the business key

The opt-in checkbox stores or widens the grant when the person approves. Widening combines the newly approved scopes with the existing set and renews expiry using auth.consentGrantLifetimeDays or the framework default. A unique user/client/resource key and conflict reread handle simultaneous initial approvals.

Let the person inspect and withdraw their approvals

Use the person’s ordinary application session, not the delegated token issued to the external tool. The owner-facing list operation is:

curl "$BACKEND_URL/oauth-consent-grants" \
  -H "Authorization: Bearer $USER_TOKEN"

The resource is scoped to the authenticated user even though its URL has no user-ID segment. Its standalone ownership relationship keeps that parent out of the path; the backend still confines the result to the caller. READ, LIST and DELETE require APP_USER; creating or updating remembered grants is reserved for the internal consent-decision flow.

Let the person choose an approval from that result by client, target resource and approved scopes. Keep the selected record’s _id as GRANT_ID, then withdraw it with:

curl -X DELETE "$BACKEND_URL/oauth-consent-grants/$GRANT_ID" \
  -H "Authorization: Bearer $USER_TOKEN"

Refresh the list to confirm the selected approval is gone. Do not treat a client ID or resource URL as the grant record ID, and do not submit another person’s user ID to choose the owner. On a later authorization request, that deleted record can no longer justify skipping consent; other client/user consent policies still apply.

Set the approval lifetime deliberately

The default is 180 days. The optional backend-authored auth.consentGrantLifetimeDays accepts an integer from 1 to 3650. Keep the existing authentication configuration and add the property there; the setting applies when a grant is created or renewed by approval. It does not rewrite an existing record’s expiresAt merely because configuration changed.

Separate remembered approval from token authority

The grant belongs to the user as a resource they can list and revoke. Withdrawing it removes the reason to skip a future prompt; it is not itself the access token. Identity scopes in the record control identity information, while operation access follows the user’s roles at request time.

Remembering approval does not create a refresh token or extend an already-issued token’s lifetime.

The authorization request names the intended resource. The code exchange reads that stored audience and rejects a different resource echoed by the token request. It then verifies the audience against the registered delegatable endpoints:

This implementation excerpt from oauth-provider-token.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const requestedAudience = grant.resource;
    if (!requestedAudience) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        'the `resource` parameter (RFC 8707) is required for the authorization_code grant');
    }
    if (request.resource && request.resource !== requestedAudience) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        'the token-request `resource` does not match the resource authorized at the authorization endpoint');
    }
    const allowedDelegatedAudiences = this.container
      .get<ResourceServerInstancesRegistryBackendService>(SAAS_SERVICE_TYPES.ResourceServerInstancesRegistry)
      .listResourceServerAudiences(DELEGATED_TOKEN_RESOURCE_SERVERS);
    if (!allowedDelegatedAudiences.includes(requestedAudience)) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        `resource '${requestedAudience}' is not a delegatable agent endpoint (A2A / MCP)`);
    }

Keep identity and business permissions separate

The delegated access claim includes the user, their authorization version and azp, which identifies the authorizing client. Business roles are resolved at request time; granting an identity scope does not grant the ability to edit a record.

Before issuance the provider checks that the user remains active and has a usable authorization version. The delegated token lifetime is capped and no refresh token is returned. The connected tool must return through authorization when it needs a new delegation.

Call through the agent contract

Present the returned Bearer token to the audience it names and use that endpoint’s MCP or A2A contract. The resource server verifies the audience before dispatching the operation. This preserves a different boundary from a machine principal, whose roles belong to the registered service rather than a consenting user.

Carry the delegation into an MCP request

Use the complete discovery and PKCE recipe to obtain accessToken, expiresIn and the original resource. For an MCP delegation, that resource is the exact chosen MCP endpoint, including a named instance when applicable. It is not the application’s general API origin.

After the MCP handshake has negotiated the locally supported 2025-06-18 revision and sent the initialized notification, this illustrative request lists the tools available to the consenting person:

const response = await fetch(resource, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${accessToken}`,
    'content-type': 'application/json',
    accept: 'application/json',
    'MCP-Protocol-Version': '2025-06-18',
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
});
if (!response.ok) throw new Error(`MCP HTTP ${response.status}`);
const envelope = await response.json();
if (envelope.error) throw new Error('MCP discovery was refused');
const tools = envelope.result.tools;

Select a tool and its argument schema from that authenticated result before calling it. Tool exposure and the person’s current business permissions still determine what can execute. An empty catalogue is not permission to invent a tool name. Other negotiated revisions require their own metadata, so let the client’s transport handle version changes.

For A2A, apply the same audience-bound Bearer to the selected A2A endpoint using its request and response contract. An agent token does not become a first-party API session merely because both endpoints belong to the same application.

Bind delegation to the intended write

The grant service stores the field, operation, minter and concrete upload URL in the token. An update grant also names the target row. This excerpt from file-upload-grant.backend.service.ts follows field validation; comments are omitted.

const constraint = await this.constraintResolver.resolve({ resourceType: target.resourceType, fieldName: target.fieldName });
this.assertDeclarationFitsConstraint(params.declared, constraint, executionContext, target);
const expiresInMinutes = params.expiresInMinutes ?? FILE_UPLOAD_GRANT_DEFAULT_MINUTES;

const metadataWithoutUrl: Omit<FileUploadGrantMetadata, 'uploadUrl' | 'producedFileId'> = {
  fieldName: target.fieldName,
  operation: target.operation,
  minter: { entityType: minter.uploadedByEntityType, id: minter.uploadedBy },
};

const token = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.FILE_UPLOAD_GRANT,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: expiresInMinutes, unit: DurationUnit.MINUTES },
  organizationId: executionContext.initiatorIds?.organizationId,
  userId: executionContext.initiatorIds?.userId,
  resourceIdentifier: String(target.resourceType),
  relatedId: target.resourceId,
  roles: [...(executionContext.initiatorRoles ?? [])],
  metadata: { ...metadataWithoutUrl, uploadUrl: params.uploadUrl },
});

Configure the addresses the recipient must reach

The HTTP mint route reads runtime.endPoints.main_backend_api.publicUrl from the application’s resolved configuration. It refuses minting when that address is absent; it does not construct a trusted upload destination from the incoming Host header. The returned upload and status URLs must be reachable by the party receiving the grant, not only from inside the application’s container network.

For a human drop page, the application must also declare a frontend service. The default frontend selected by configuration needs its own runtime.endPoints[frontendServiceName].publicUrl; the service must be present in frontendServices. The grant service builds uploadPageUrl from that address and the public upload-grant route. Configure deployment addresses through the normal application environment setup, then inspect the resolved values instead of adding a second URL authority inside a custom caller.

Check the returned uploadUrl and statusUrl, and inspect whether uploadPageUrl is present before offering a browser link. A headless deployment can accept the delegated upload through the backend contract; it does not acquire a hosted upload page merely by minting a grant.

Use the returned upload instructions

Both mint doors return the upload URL, a credential header, shell upload commands and a status URL. When a frontend is configured, the response also supplies the browser drop-page URL. Use those returned values so the client follows the exact bound route.

The default lifetime is 15 minutes with a framework ceiling of 60 minutes. Anonymous sessions and consumable-token callers cannot mint another grant. Ordinary operation authorization still applies; the grant does not create permission to read or modify other records.

Carry one file through the complete handoff

This illustrative browser JavaScript follows the Wonder Todos attachment test. recordUrl is the existing todo-list’s API URL, bearer belongs to a caller allowed to update it, and file is a selected File. Start with an empty attachments field: this example replaces its value with one file. An add-to-existing workflow must preserve the current IDs and handle concurrent edits.

async function attachFile({ recordUrl, bearer, file }) {
  const readJson = async (response) => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  };
  const authority = { authorization: `Bearer ${bearer}` };
  const jsonHeaders = { ...authority, 'content-type': 'application/json' };

  const grant = await readJson(await fetch(`${recordUrl}/files/attachments/grant`, {
    method: 'POST',
    headers: jsonHeaders,
    body: JSON.stringify({ expiresInMinutes: 10 }),
  }));

  const form = new FormData();
  form.append('file', file, file.name);
  await readJson(await fetch(grant.uploadUrl, {
    method: 'POST',
    headers: { [grant.uploadHeader.name]: grant.uploadHeader.value },
    body: form,
  }));

  const status = await readJson(await fetch(grant.statusUrl));
  if (status.state !== 'redeemed' || !status.file?.fileId) {
    throw new Error('The grant has not produced a file ID');
  }
  const attachments = {
    fileIds: [status.file.fileId],
    updatedAt: new Date().toISOString(),
  };

  await readJson(await fetch(recordUrl, {
    method: 'PUT',
    headers: jsonHeaders,
    body: JSON.stringify({ attachments }),
  }));
  return readJson(await fetch(recordUrl, { headers: authority }));
}

The upload request carries only the returned grant header; the final write and read use the original Bearer. Let FormData set the multipart content type. For a human handoff, show uploadPageUrl and resume at the status read after upload instead of transferring bytes in this function. That browser URL requires a configured frontend.

Inspect the record in the final response (response.data for an enveloped response, otherwise the response itself): it should contain the same ID in attachments.fileIds. A single-file field instead uses { fileId, updatedAt }. A redeemed grant proves that bytes produced a file, not that scanning has finished or the parent accepted it: pending scanning can still delay attachment. Check file readiness and retain the produced ID while resolving a pending result; do not redeem the same grant again to retry the parent write.

Handle retries according to the claim point

Route matching and actionable file validation happen before the single-use token is consumed. Consumption occurs before the file row and byte write, so concurrent redemptions cannot both start an accepted upload. A refusal before that point can leave the grant usable; a failure after consumption requires a new grant.

The upload is attributed to the minter recorded in the grant. Possession of the link does not establish the identity of the person holding it. Status exposes the produced file ID when write-back succeeds, while the final resource create or update uses the caller’s normal operation permissions.

Give an MCP caller the same upload path

Opt the parent CREATE or UPDATE operation into MCP with mcp: { exposed: true, description: '…' } on its supported default URL-bearing variant. When that request contains a user-uploadable file field, Wildo derives the upload-grant tool and adds instructions to the parent’s description. There is no second upload tool implementation to author.

For a resource named todos with an exposed CREATE operation and an attachments field, the derived name is todos__create.upload_grant.attachments. Discover the actual name and input schema in the server’s tool list: UPDATE also requires the parent’s instance identifier, while CREATE does not.

This illustrative tools/call request declares the file before minting, so an impossible MIME type or size can be refused before upload:

{
  "method": "tools/call",
  "params": {
    "name": "todos__create.upload_grant.attachments",
    "arguments": {
      "name": "inspection.jpg",
      "mimeType": "image/jpeg",
      "size": 184320,
      "expiresInMinutes": 10
    }
  }
}

Read the grant object from the tool result, then use the returned instructions rather than constructing an upload URL yourself.

A grant inherits the exposed parent operation’s gating; it does not grant the caller broader record access. Upload success, processing readiness and successful parent attachment remain separate steps. Treat the header and token-bearing page/status URLs as bearer credentials and keep them out of public logs.