Identity Groups

Identity groups let you organize non-human identities by team, function, environment, or any dimension that aligns with your operational model. Instead of managing policies and access rules for individual identities, you define them once at the group level and every member inherits them automatically.

Why Use Groups

Managing identities individually does not scale. As your organization grows from dozens to thousands of NHIs, group-based governance becomes essential:

• Policy inheritance — Assign a policy to a group and every member identity is automatically covered. Add a new identity to the group and it immediately inherits all group policies.
• Bulk operations — Suspend, activate, or rotate credentials for an entire group in a single action.
• Organizational alignment — Mirror your team structure, service architecture, or deployment topology in your identity model.
• Simplified auditing — Review access and risk posture at the group level rather than inspecting hundreds of individual identities.

Group Structure

A group is a named collection of identities with its own metadata and policy bindings.

Field	Type	Description
id	string	Unique group identifier (UUID v4)
name	string	Human-readable group name (unique within tenant)
description	string	Purpose or scope of the group
metadata	JSON	Arbitrary key-value pairs (e.g., cost center, business unit)
tags	string[]	Labels for filtering and nested group queries
memberCount	number	Current number of identities in the group
policies	string[]	IDs of policies bound to this group
createdAt	datetime	Timestamp of group creation
updatedAt	datetime	Timestamp of last modification

Example Group Object

{
  "id": "grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a",
  "name": "payments-team-production",
  "description": "All production NHIs owned by the payments team",
  "metadata": {
    "team": "payments",
    "environment": "production",
    "costCenter": "ENG-042"
  },
  "tags": ["production", "pci-scope"],
  "memberCount": 14,
  "policies": [
    "pol_rotation-90d",
    "pol_ip-allowlist-prod",
    "pol_risk-threshold-50"
  ],
  "createdAt": "2025-11-01T09:00:00Z",
  "updatedAt": "2026-03-18T16:45:00Z"
}

Grouping Strategies

Choose a grouping strategy that matches how your organization thinks about identity ownership and governance.

By Team

Group identities by the team that owns and operates them. This is the most common strategy and aligns policy ownership with operational responsibility.

payments-team-production
├── payment-processor (SERVICE_ACCOUNT)
├── stripe-webhook-handler (API_KEY)
├── billing-cron-job (CI_CD)
└── payment-fraud-detector (AI_AGENT)

By Function

Group identities by their operational function, regardless of which team owns them. Useful for applying function-specific policies such as credential rotation intervals or IP restrictions.

ci-cd-pipelines
├── deploy-pipeline-staging (CI_CD)
├── deploy-pipeline-production (CI_CD)
├── terraform-plan-runner (CI_CD)
└── argocd-sync-agent (CI_CD)

By Environment

Group identities by deployment environment to enforce environment-specific access controls, network restrictions, and risk thresholds.

production-identities
├── api-gateway (SERVICE_ACCOUNT)
├── payment-processor (SERVICE_ACCOUNT)
├── deploy-pipeline-production (CI_CD)
└── monitoring-agent (SERVICE_ACCOUNT)

Tip

Identities can belong to multiple groups simultaneously. A service account can be a member of both payments-team-production and production-identities, inheriting policies from both groups.

Managing Groups

Create a Group

curl -X POST https://app.veraid.io/api/v1/groups \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payments-team-production",
    "description": "All production NHIs owned by the payments team",
    "metadata": {
      "team": "payments",
      "environment": "production"
    },
    "tags": ["production", "pci-scope"]
  }'

Add Identities to a Group

Add one or more identities to an existing group. Identities immediately inherit all group policies.

curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/members \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identityIds": [
      "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d",
      "idt_7b2e50a8-ceea-462a-a5e7-8f14e45fb72c"
    ]
  }'

Remove Identities from a Group

curl -X DELETE https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/members \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identityIds": [
      "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d"
    ]
  }'

List Group Members

curl -X GET "https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/members?page=1&limit=50" \
  -H "Authorization: Bearer kd_live_your_api_key"

Group-Based Policy Assignment

Policies assigned to a group apply to every member identity. When an identity belongs to multiple groups, policies from all groups are combined — the most restrictive rule wins in case of conflicts.

Bind a Policy to a Group

curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/policies \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "policyIds": [
      "pol_rotation-90d",
      "pol_ip-allowlist-prod"
    ]
  }'

Note

Group policy bindings are additive. An identity’s effective policy set is the union of its directly assigned policies and all policies inherited from its groups. See Policies for details on policy evaluation order.

Bulk Operations

Groups enable you to perform lifecycle actions across many identities at once.

Bulk Suspend

Suspend all identities in a group. Useful during incident response or owner offboarding.

curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/suspend \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident — suspending all payments-team identities pending investigation"
  }'

Bulk Activate

Reactivate all suspended identities in a group after an investigation is resolved.

curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/activate \
  -H "Authorization: Bearer kd_live_your_api_key"

Bulk Credential Rotation

Trigger credential rotation for every identity in a group. Each identity’s credentials are rotated according to their individual rotation policies, with grace periods honored.

curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/rotate-credentials \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Quarterly security rotation",
    "gracePeriodHours": 24
  }'

Caution

Bulk operations are processed asynchronously. The API returns a 202 Accepted response with a job ID. Use GET /api/v1/jobs/{jobId} to monitor progress. Large groups may take several minutes to process.

Group Risk Overview

The group detail view on the dashboard provides an aggregated risk overview:

• Average risk score across all members
• Highest-risk members ranked by score
• Risk distribution histogram showing how members fall across Low, Medium, High, and Critical levels
• Trend analysis showing how the group’s aggregate risk has changed over time

This view helps security teams quickly identify which groups require attention and drill down into specific high-risk identities.

What’s Next

• Credential Overview — Understand credential types, formats, and encryption
• Credential Rotation — Configure automated rotation policies
• Policies Overview — Define access policies for groups and individual identities