User Directory & SCIM

VeraID v2.0 includes a built-in user directory for managing human identities alongside your non-human identities. The directory supports user lifecycle management, group-based access control, and SCIM 2.0 provisioning for automated sync with external identity providers like Okta and Microsoft Entra ID.

User lifecycle management

User states

Every user in the VeraID directory moves through a defined lifecycle:

State	Description	Can Sign In
INVITED	Invitation sent, user has not yet accepted	No
ACTIVE	User has accepted invitation and is fully operational	Yes
SUSPENDED	Temporarily disabled by an admin or automated policy	No
DEPROVISIONED	Permanently disabled, scheduled for deletion	No

Creating users

Create users through the admin UI or API:

curl -X POST https://app.veraid.io/api/v1/directory/users \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "department": "Engineering",
    "title": "Staff Engineer",
    "groups": ["engineering", "platform-team"],
    "roles": ["user"],
    "metadata": {
      "employeeId": "EMP-1234",
      "costCenter": "CC-5678",
      "startDate": "2026-04-01"
    },
    "sendInvitation": true
  }'

Response:

{
  "id": "usr_abc123",
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "status": "INVITED",
  "groups": ["engineering", "platform-team"],
  "roles": ["user"],
  "createdAt": "2026-03-26T10:00:00Z"
}

Updating users

curl -X PATCH https://app.veraid.io/api/v1/directory/users/{userId} \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "department": "Platform Engineering",
    "title": "Principal Engineer",
    "groups": ["engineering", "platform-team", "architecture"],
    "metadata": {
      "costCenter": "CC-9999"
    }
  }'

Suspending and deprovisioning users

# Suspend a user (reversible)
curl -X POST https://app.veraid.io/api/v1/directory/users/{userId}/suspend \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Leave of absence" }'

# Deprovision a user (permanent)
curl -X POST https://app.veraid.io/api/v1/directory/users/{userId}/deprovision \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Employee departure",
    "transferOwnedNhisTo": "usr_backup_owner",
    "revokeAllSessions": true,
    "revokeOwnedNhis": true
  }'

When a user is deprovisioned:

• All active sessions are immediately revoked.
• All NHIs owned by the user are suspended or transferred (configurable).
• All OIDC/SAML sessions at connected SPs are terminated via back-channel logout.
• An audit log entry is created with the deprovisioning reason and actor.

Caution

Deprovisioning is a permanent action. The user account is retained for 30 days for audit purposes but cannot be reactivated. Use suspend for temporary disablement.

---

Group-based access

Groups organize users and control access to applications, NHIs, and policies.

Managing groups

# Create a group
curl -X POST https://app.veraid.io/api/v1/directory/groups \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "platform-team",
    "displayName": "Platform Team",
    "description": "Platform engineering team members",
    "metadata": {
      "costCenter": "CC-5678",
      "manager": "usr_manager123"
    }
  }'

# Add members to a group
curl -X POST https://app.veraid.io/api/v1/directory/groups/{groupId}/members \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["usr_abc123", "usr_def456", "usr_ghi789"]
  }'

Group-based policies

Groups can be referenced in conditional access policies and OIDC/SAML attribute mapping:

{
  "name": "Allow platform team to access production APIs",
  "conditions": {
    "groups": ["platform-team"],
    "applications": ["production-api"]
  },
  "effect": "ALLOW"
}

Groups are automatically included in OIDC groups claim and SAML group assertions when the corresponding scope or attribute mapping is configured.

---

Inbound SCIM 2.0 provisioning

Inbound SCIM allows external identity providers (Okta, Microsoft Entra ID, OneLogin) to automatically provision, update, and deprovision users in VeraID.

Setting up inbound SCIM

1. Navigate to Settings > Directory > SCIM Provisioning > Inbound.
2. Click Enable Inbound SCIM.
3. VeraID generates a SCIM base URL and bearer token:

SCIM Base URL: https://app.veraid.io/api/scim/v2/{orgId}
SCIM Token:    scim_tok_abc123...

4. Configure your external IdP with these values.

Configuring Okta

In your Okta admin console:

1. Go to Applications > Add Application > SCIM 2.0 Test App.
2. Under Provisioning > Integration, enter:
   • SCIM connector base URL: https://app.veraid.io/api/scim/v2/{orgId}
   • Unique identifier field: userName
   • Authentication mode: HTTP Header
   • Authorization: Bearer scim_tok_abc123...
3. Enable the desired provisioning features:
   • Create Users — Provision new users from Okta to VeraID.
   • Update User Attributes — Sync profile changes.
   • Deactivate Users — Deprovision users when removed from the Okta app.
4. Test the connection and save.

Configuring Microsoft Entra ID

In the Azure portal:

1. Go to Enterprise Applications > New Application > Non-gallery application.
2. Under Provisioning > Provisioning Mode, select Automatic.
3. Enter:
   • Tenant URL: https://app.veraid.io/api/scim/v2/{orgId}
   • Secret Token: scim_tok_abc123...
4. Map attributes (Entra ID fields to VeraID SCIM fields).
5. Test the connection, then enable provisioning.

Supported SCIM operations

Operation	Endpoint	Description
List Users	GET /Users	Retrieve users with filtering
Get User	GET /Users/{id}	Retrieve a specific user
Create User	POST /Users	Provision a new user
Update User	PATCH /Users/{id}	Update user attributes
Replace User	PUT /Users/{id}	Replace all user attributes
Delete User	DELETE /Users/{id}	Deprovision a user
List Groups	GET /Groups	Retrieve groups with filtering
Get Group	GET /Groups/{id}	Retrieve a specific group
Create Group	POST /Groups	Create a new group
Update Group	PATCH /Groups/{id}	Add/remove group members
Delete Group	DELETE /Groups/{id}	Delete a group

SCIM attribute mapping

SCIM Attribute	VeraID Field	Required
userName	email	Yes
name.givenName	firstName	Yes
name.familyName	lastName	Yes
displayName	displayName	No
active	status (ACTIVE/SUSPENDED)	Yes
emails[primary].value	email	Yes
title	title	No
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department	department	No
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager	managerId	No

---

Outbound SCIM provisioning

Outbound SCIM allows VeraID to push user and group changes to downstream applications (e.g., provisioning users into SaaS tools).

Setting up outbound SCIM

curl -X POST https://app.veraid.io/api/v1/directory/scim/outbound \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provision to Jira",
    "baseUrl": "https://jira.example.com/scim/v2",
    "authType": "bearer",
    "authToken": "jira_scim_token_abc123",
    "syncUsers": true,
    "syncGroups": true,
    "attributeMapping": {
      "userName": "user.email",
      "displayName": "user.fullName",
      "active": "user.isActive"
    },
    "filters": {
      "includeGroups": ["engineering", "product"]
    }
  }'

Outbound provisioning events

VeraID triggers outbound SCIM operations when:

Event	SCIM Operation
User created in VeraID	POST /Users
User profile updated	PATCH /Users/{id}
User added to group	PATCH /Groups/{id}
User removed from group	PATCH /Groups/{id}
User suspended	PATCH /Users/{id} (set active: false)
User deprovisioned	DELETE /Users/{id}

---

SCIM token management

Creating tokens

curl -X POST https://app.veraid.io/api/v1/directory/scim/tokens \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okta SCIM Token",
    "expiresInDays": 365,
    "scopes": ["users:read", "users:write", "groups:read", "groups:write"]
  }'

Response:

{
  "id": "scim_tok_abc123",
  "name": "Okta SCIM Token",
  "token": "scim_tok_full_token_shown_once",
  "expiresAt": "2027-03-26T10:00:00Z",
  "scopes": ["users:read", "users:write", "groups:read", "groups:write"],
  "createdAt": "2026-03-26T10:00:00Z"
}

Caution

SCIM tokens are displayed only once at creation time. Store them securely in your IdP’s configuration. If a token is compromised, revoke it immediately and generate a new one.

Listing tokens

curl -X GET https://app.veraid.io/api/v1/directory/scim/tokens \
  -H "Authorization: Bearer kd_live_your_api_key"

Revoking tokens

curl -X DELETE https://app.veraid.io/api/v1/directory/scim/tokens/{tokenId} \
  -H "Authorization: Bearer kd_live_your_api_key"

Token rotation

To rotate a SCIM token without downtime:

1. Create a new token with the same scopes.
2. Update the external IdP configuration with the new token.
3. Verify provisioning works with the new token.
4. Revoke the old token.

---

Audit logging

All directory operations are recorded in the audit log:

Event	Description
user.created	New user provisioned (manual or SCIM)
user.updated	User attributes modified
user.suspended	User suspended
user.deprovisioned	User permanently disabled
user.reactivated	Suspended user reactivated
group.created	New group created
group.member_added	User added to group
group.member_removed	User removed from group
scim.token_created	New SCIM token generated
scim.token_revoked	SCIM token revoked
scim.sync_completed	SCIM sync operation completed

---

Next steps

Authentication Methods

Configure how directory users authenticate. Authentication Methods

Federation

Connect external IdPs for enterprise SSO with JIT provisioning. Federation Guide

Conditional Access

Create policies based on user groups and directory attributes. Conditional Access