# Manage team and service account access in one place

Groups unify access management for organization members and API keys. Define role-scoped rules once. Connect your identity provider for automatic assignment. No per-user configuration.

## The problem

### Per-user access doesn't scale

Individual permission management breaks down as teams grow. Access drifts. Offboarding is manual. Human and machine access diverge.

### Managing individuals at scale is a full-time job

As organizations grow, per-user permission management becomes unsustainable. Every new hire, departure, or role change requires a manual update to each person's access.

### Separate access models for users and API keys create gaps

When human access and machine access are managed differently, permissions drift apart. CI/CD keys end up with more or less access than intended.

### No integration with identity providers means manual sync

Without a connection to your IdP, group membership must be updated by hand when people change teams. Outdated access is the result.

## Our solution

### Centralized access through groups and rules

Groups hold one or more rules. Each rule defines a role and an optional resource scope. Users and API keys assigned to a group inherit all its rules. Update the group, and every member's access updates immediately.

### How groups work

1. Create a group with a name and optional description.
2. Add group rules: each rule assigns a role and an optional resource scope (namespace, graph, or subgraph).
3. Add organization members and API keys to the group — both inherit the same rules.
4. For SSO organizations, configure OIDC mappers to auto-assign users to groups based on IdP attributes.
5. SCIM provisioning can create and deactivate users automatically, keeping your IdP user list in sync with Cosmo.
6. To delete a group, Cosmo's safe deletion workflow reassigns its members and keys to another group first.

## Groups & Group Rules

### Before & After

| Before Cosmo | With Cosmo |
| --- | --- |
| Individual permission management for every user | Group-based access: change one group, update everyone |
| Separate systems for user and API key permissions | Unified groups for both humans and automation |
| Manual group membership updates when teams change | Automatic group assignment via OIDC mapper |
| Risk of orphaned access when deleting groups | Safe deletion workflow with automatic reassignment |

### Safe lifecycle

#### Safe to delete, safe to modify

Deleting a group with active members or keys triggers a reassignment workflow. Cosmo shows what is using the group and requires you to select a destination group before deletion proceeds. No accidental access loss.

Built-in groups (admin, developer, viewer) cannot be modified or deleted. Custom groups can be edited at any time.

## How Cosmo Groups work

01 Built-in defaults included.

### Create

Create a group with a name and optional description. Built-in admin, developer, and viewer groups are available by default and cannot be modified or deleted.

02 Multiple rules per group.

### Configure rules

Add rules to the group. Each rule assigns a role and an optional resource scope. A group can have multiple rules with different roles and scopes.

03 Users and keys, unified.

### Assign members

Add organization members and API keys to the group. Both types of principals inherit all permissions from the group's rules immediately.

04 IdP-driven assignment.

### Automate

Configure OIDC mappers to assign users to groups based on identity provider attributes. SCIM provisioning can create and deactivate users automatically.

## What's included

### One group system for your whole organization

The same group and rule system applies to organization members and API keys. One model. No separate configuration for human and machine access.

### Multiple rules per group

A group can contain multiple rules with different roles and scopes. Give a team namespace admin access for their namespace and viewer access elsewhere through one group.

### OIDC mapper support

Configure OIDC mappers to assign users to groups automatically based on identity provider attributes. Group membership stays synchronized with your IdP without manual updates.

### Safe deletion workflow

Deleting a group with active assignments triggers a reassignment step. Members and keys move to a new group before deletion completes. Accidental access loss is prevented by design.

## Set up groups for your organization

Start on Scale or Enterprise to enable RBAC and create groups.

## FAQ

### Groups & Group Rules on Cosmo

- What plan is Groups available on?
- What are the built-in groups?
- Can a group have multiple rules?
- Can API keys be assigned to groups?
- What happens when I delete a group?
- Can groups be automatically populated from my identity provider?

Full details in the [groups documentation](https://cosmo-docs.wundergraph.com/studio/groups).