# ScimGroupsController

**Kind:** Controller

**Source:** [`atloria-monorepo/apps/api/src/scim/scim-groups.controller.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/scim/scim-groups.controller.ts#L28)

SCIM 2.0 Groups endpoint (virtual, Phase-2). Backed by ScimGroupMapping —
group membership propagates the mapped role/audience onto member users.
Kept minimal on purpose: Okta provisions Users-only just fine.

`ScimGroupsController` exposes the SCIM 2.0 Groups endpoint for identity providers such as Okta. It manages virtual groups backed by `ScimGroupMapping`, where group membership causes the mapped role or audience to be propagated to member users. The controller is intentionally minimal because user-only provisioning remains the primary supported SCIM workflow.

## Diagram

```mermaid
graph LR
  IdP[Identity Provider<br/>Okta] -->|SCIM Groups requests| Controller[ScimGroupsController]
  Controller --> Mapping[ScimGroupMapping]
  Mapping --> Role[Mapped Role / Audience]
  Controller --> Members[Group Member Users]
  Role --> Members
```

## Usage

```ts
const response = await fetch("https://api.example.com/scim/v2/Groups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCIM_BEARER_TOKEN}`,
    "Content-Type": "application/scim+json",
  },
  body: JSON.stringify({
    schemas: ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    displayName: "Support Team",
    members: [
      {
        value: "user-scim-id-123",
        display: "support@example.com",
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Unable to provision SCIM group: ${response.statusText}`);
}

const group = await response.json();
console.log(group.id);
```

## AI Coding Instructions

- Preserve SCIM 2.0 request and response conventions, including SCIM media types, schemas, IDs, and member payload shapes.
- Treat groups as mappings rather than independent authorization records; membership changes must remain synchronized with `ScimGroupMapping`.
- Ensure mapped roles or audiences are propagated consistently when members are added, removed, or updated.
- Keep the endpoint intentionally minimal and compatible with IdPs that primarily provision users, especially Okta.
- Avoid introducing group behavior that bypasses existing user, role, audience, or SCIM authentication flows.

## Relationships

- MODULE_DECLARES → `list`
- MODULE_DECLARES → `get`
- MODULE_DECLARES → `create`
- MODULE_DECLARES → `patch`
- DEPENDS_ON → `ScimService`

## Referenced By

- `ScimModule` (MODULE_DECLARES)