FAQ

Frequently asked questions about Veza's Access AuthZ APIs for automated provisioning and access management

This document addresses common questions about Access AuthZ APIs for automated user provisioning, access grants, and deprovisioning across enterprise applications.

Overview

The questions in this document are designed to introduce key concepts and address common questions that often arise during Access AuthZ implementations. Please contact your support team with additional questions and feedback. Note that specific functionality may depend on the features and integrations enabled in your environment.

Learning more

Your Access AuthZ configuration can be straightforward or complex, depending on your organization's needs. To learn more about general implementation patterns, see Quick Start and Prerequisites.

See also:

• Create Access Request

• Integrations

• SCIM integration

Getting Started

What's the difference between Direct and Policy Identity Access Requests

Both approaches use the same underlying Access Request system, but differ in how you specify the target user:

Direct Access Requests - You provide the specific entity ID from the Access Graph (e.g., assignee_entity_id). Use this when:

• Managing access without Policy Identities from Veza Lifecycle Management.

• Working directly with Access Graph entities

• Testing and development

Policy Identity Access Requests - Convenience endpoints that works with Policy Identities managed by Lifecycle Management policies. The endpoint automatically looks up the correct entity IDs based on the policy identity. Use this when users are managed through established Policies, and you want to use existing policy identity mappings

API Endpoints:

• Direct: POST /api/private/lifecycle_management/access_requests

• Policy Identity: POST /api/private/lifecycle_management/policies/{policy_id}/identities/{id}:access_request

See CreateAccessRequest for the direct API reference. Both endpoints create the same underlying AccessRequest object.

Which integrations support Access AuthZ

Any integration that supports Lifecycle Management Actions can be used with the Access Request APIs. This includes:

• Native integrations: Active Directory, Azure AD, Okta, Snowflake, and many others

• SCIM integration: For any SCIM-compatible system without native support

• Custom Applications: You can enable provisioning for custom integrations created with the Open Authorization API (OAA), for both resource-level visibility and user access management. The application must provide SCIM endpoints for user management and be enabled for provisioning. See SCIM provisioning with Custom Applications for full instructions.

To be eligible for Access Request API operations, the integration must have Lifecycle Management enabled. See Prerequisites and Setup for instructions on configuring this setting.

What permissions do you need

The Access Request APIs require:

• An API token with Admin permissions

• Access Requests enabled in Lifecycle Management settings

• Grant without approval enabled (for automatic execution)

• Sufficient integration permissions for Veza to make changes in the target integration

See Prerequisites and Setup for complete requirements.

What fields are required to provision a user

The required fields depend on your target integration. Each integration (Active Directory, Okta, SCIM, and so on) has different requirements for user provisioning.

Two Ways to Discover Required Fields:

1. Check the Integration Guide (Recommended for Getting Started)

Each Lifecycle Management integration guide documents the supported attributes and requirements:

• Active Directory LCM

• Azure AD / Entra ID LCM

• Okta LCM

• SCIM LCM

• Full list of integrations

These guides include tables showing which attributes are required compared to optional for user creation and updates.

2. Use the Lifecycle Manager API (Recommended for Programmatic Discovery)

You can query the Lifecycle Manager API to discover the schema for a specific integration:

Get Integration Schema via API

GET /api/v1/providers/datasources/lifecycle_managers/{lifecycle_manager_id}

Example Request:

curl -X GET \
  "https://your-instance.vezacloud.com/api/v1/providers/datasources/lifecycle_managers/lcm-123" \
  -H "authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "value": {
    "id": "lcm-123",
    "enabled": true,
    "datasource": {
      "id": "ds-456",
      "name": "SCIM Integration - HR System",
      "datasource_type": "LIFECYCLE_MANAGER",
      "agent_type": "scim",
      "state": "ENABLED"
    },
    "definition": {
      "actions": [
        {
          "type": "SYNC_IDENTITIES",
          "idempotent": true,
          "input_entity_types": [
            {
              "name": "User",
              "description": "The user identity to sync",
              "available_entity_types": ["SCIMUser"]
            }
          ],
          "definition": {
            "@type": "type.googleapis.com/lifecyclemanagement.v1.SyncIdentitiesDefinition",
            "entity_type": "SCIMUser",
            "create_allowed": true,
            "available_attributes": [
              {
                "name": "user_name",
                "attribute_type": "STRING",
                "required": true,
                "unique_identifier": true,
                "hint": "Username for the account"
              },
              {
                "name": "email",
                "attribute_type": "STRING",
                "required": true,
                "hint": "User's email address"
              },
              {
                "name": "given_name",
                "attribute_type": "STRING",
                "required": false,
                "hint": "User's first name"
              },
              {
                "name": "family_name",
                "attribute_type": "STRING",
                "required": false,
                "hint": "User's last name"
              },
              {
                "name": "active",
                "attribute_type": "BOOL",
                "required": false,
                "hint": "Whether the account is active"
              }
            ]
          }
        },
        {
          "type": "MANAGE_RELATIONSHIPS",
          "idempotent": true,
          "definition": {
            "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsDefinition",
            "available_entity_types": ["SCIMGroup"],
            "assignee_entity_types": ["SCIMUser"]
          }
        }
      ]
    }
  }
}

Understanding the Schema:

• required: true - This field must be included in your API request. If omitted, the request will fail.

• unique_identifier: true - This field uniquely identifies the user in the target system. Used for lookups and updates.

• type - The data type (string, boolean, integer, etc.)

• default - If present, this value is used when the field is omitted

Key Concepts:

Concept	Definition	Example
Required Attribute	Must be provided in API request for the operation to succeed	user_name, email for user creation
Unique Identifier	Attribute that uniquely identifies the entity in the target system. Can be used to locate an existing user for updates. Only one unique identifier is needed per request.	user_name for SCIM, samAccountName for Active Directory
Optional Attribute	Can be provided but not required. May have default values.	given_name, phone_number

Using Unique Identifiers:

When updating a user, you have two options to specify which user:

1. Use the Access Graph entity ID - Provide assignee_entity_id with the Veza graph ID

2. Use a unique identifier - Provide any attribute marked as unique_identifier: true in the schema

Example: Update User by Username (Unique Identifier)

{
  "datasource_id": "lcm-123",
  "request_type": "GRANT",
  "request_source": "ACCESS_REQUEST",
  "reason": "Update user email address",
  "assignee_entity_type": "OAA.SCIM.User",
  "sync_config": {
    "config": {
      "continuous_sync": true,
      "entity_attribute_transformers": [
        {
          "destination_attribute": "user_name",
          "destination_value_formatter": "jsmith",
          "unique_identifier": true,
          "continuous_sync": true
        },
        {
          "destination_attribute": "email",
          "destination_value_formatter": "[email protected]",
          "continuous_sync": true
        }
      ]
    }
  }
}

In this example, Veza will locate the user by user_name (the unique identifier) and update their email address. The continuous_sync: true on each attribute ensures existing user values are updated.

Best Practices:

1. Always check required fields first - Query the lifecycle manager schema before building your integration

2. Handle schema changes - Integration schemas can change when Veza adds new capabilities

3. Test with minimal fields - Start with only required fields, then add optional fields as needed

4. Validate data types - Ensure your values match the expected type (string, boolean, and so on)

5. Use unique identifiers carefully - When updating users, provide either assignee_entity_id OR a unique identifier attribute, not both

How do you find entity IDs for Access Requests

You can retrieve entity metadata using Query Builder in the Veza console or via the API.

Using the Veza Console:

Step 1: Navigate to Query Builder

1. Log in to your Veza instance

2. Go to Access Visibility > Query Builder in the main navigation menu

Step 2: Build Your Query

1. Select the source entity type from the dropdown (e.g., "Active Directory User", "Okta User")

2. (Optional) Add filters to narrow results:

   • Use Attribute Filters to filter by specific properties (e.g., is_active = true)

   • Filter by Veza tags

   • Filter by relationships to specific resources

3. Click Run Query or let results update automatically

The results table displays matching entities with their key properties. To see full entity details, including the entity ID:

1. Click on an entity name in the results table

2. A slideout panel opens to show the entity details, including:

   • Entity ID (the unique identifier you need for API calls)

   • Entity Type

   • All entity properties and attributes Veza has discovered

Using the Query Builder API:

You can also use Veza's Query Builder API to find user and group IDs:

Example: Query for Active Directory Users

curl -X POST "https://your-instance.vezacloud.com/api/v1/assessments/query_spec:nodes" \
  -H "authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "query_type": "SOURCE_TO_DESTINATION",
  "node_relationship_type": "EFFECTIVE_ACCESS",
  "source_node_types": {
    "nodes": [
      {
        "node_type": "ActiveDirectoryUser"
      }
    ]
  }
}'

Example Response Structure

{
  "values": [
    {
      "id": "unique-entity-id-123",
      "type": "ActiveDirectoryUser",
      "properties": {
        "name": "john.smith",
        "email": "[email protected]",
        "is_active": true,
        "created_date": "2024-01-15T10:30:00Z"
      },
      "destination_node_count": 42,
      "permissions": [],
      "risk_level": "WARNING",
      "raw_permissions": [],
      "effective_permissions": []
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjEwMH0=",
  "has_more": true
}

The id field in each result is what you need for Access Grant API calls. Copy this value to use as assignee_entity_id or when identifying users and groups.

How do you find Lifecycle Manager datasource IDs

Access AuthZ APIs require the Lifecycle Manager datasource ID, which is different from the base datasource ID you see in the Integrations list.

Understanding Datasource IDs

Critical: Access AuthZ APIs require the Lifecycle Manager datasource ID, not the base datasource ID.

Two Types of IDs

1. Base Datasource ID - The integration itself in Veza (shown in Integrations list)

2. Lifecycle Manager Datasource ID - Created when you enable "Enable for Lifecycle Manager"

Common mistake: Using the base datasource ID causes "datasource not found" errors.

Finding Lifecycle Manager Datasource IDs

curl -X GET "https://your-instance.vezacloud.com/api/v1/providers/datasources/lifecycle_managers" \
  -H "authorization: Bearer YOUR_API_TOKEN"

Response shows available lifecycle managers:

{
  "values": [
    {
      "id": "0198cfaf-1f97-7698-a760-05b98833ffd3",
      "datasource": {
        "name": "SCIM DEMO Lifecycle Management",
        "provider_id": "0198cf75-db63-7709-86c3-8ec8fc124382"
      },
      "definition": {
        "actions": [
          {"type": "SYNC_IDENTITIES"},
          {"type": "MANAGE_RELATIONSHIPS"}
        ]
      }
    }
  ]
}

Use the id field in your Access AuthZ API calls.

The actions array shows what the integration supports:

• SYNC_IDENTITIES - Can create, update, and disable user accounts

• MANAGE_RELATIONSHIPS - Can add/remove users from groups and roles

Troubleshooting

How can you verify your environment is configured correctly

Before making your first API call, follow these verification steps:

1. Test API authentication - Verify token works with a simple GET request

2. Check Access Requests enabled - Confirm the feature is displayed in Lifecycle Management settings

3. Verify admin permissions - Ensure API token's user has Admin role

4. Test integration - Confirm target integration is active and syncing

5. Get datasource IDs - List lifecycle managers to find correct IDs

"Access Requests not enabled" Error

Solution: Enable at Lifecycle Management → Settings → Access Request Settings

"Datasource not found" Error

Solution: You're using the base datasource ID instead of Lifecycle Manager ID. Use the lifecycle managers API to get the correct ID. See How do you find Lifecycle Manager datasource IDs

"Insufficient permissions" Error

Solution: Verify:

• API token belongs to admin user

• Target integration has proper credentials

• Grant without approval is enabled

"Feature not enabled" Error

Solution: Contact Veza support to enable required feature flags for your tenant.

Why is my request stuck in PLAN_SELECTED state

Common causes for this status include:

• Target integration offline: Check integration status in Veza

• Authentication issues: Verify credentials for the target system

• Network connectivity: Ensure Veza can reach your target system

• LCM not enabled: Confirm Lifecycle Management is enabled for the integration (see Prerequisites)

Check the error_message field in the request status for specific details.

Why do you get "Entity not found" errors

This error usually indicates issues with:

• Incorrect entity IDs: Use Query Builder API to verify the ID exists

• Outdated graph data: Trigger a data extraction or wait for the next scheduled sync

• Wrong entity types: Ensure you're using the correct type (e.g., "ActiveDirectoryUser" not "AdUser")

My request was completed, but nothing changed in the target system. Why

If no provisioning actions occurred, check the:

• LCM datasource ID: Ensure you are using the Lifecycle Manager ID, and not the base datasource ID

• Integration permissions: Verify the integration has the required permissions on the target system to manage users and access controls

• Request type: Confirm you used the correct request_type ("GRANT" or "REVOKE")

User Management

How do you create a new user account

Use the Direct API with sync_config for user creation.

See the CreateAccessRequest endpoint documentation for complete examples.

Can you deactivate a user without deleting them

Yes, use the deprovision_config with request_type: "REVOKE" to set the user's active status to false (see integration guides for the exact behavior for the target application). This preserves the user record while disabling access.

See the CreateAccessRequest endpoint documentation for examples.

How do you update existing user attributes

Use sync_config with continuous_sync: true and the assignee_entity_id to update specific attributes on an existing user.

To find available attributes for your integration:

Use the GET lifecycle managers API to discover supported attributes:

GET /api/v1/providers/datasources/lifecycle_managers/{lifecycle_manager_id}

Key points about updating attributes:

• assignee_entity_id is required to identify which existing entity to update

• continuous_sync: true is required at both the config level and on individual attributes for successful update operations

• If you don't specify assignee_entity_id, include one attribute with unique_identifier: true to locate the user

• The request must include all required attributes for the integration (e.g., user_name for SCIM)

• Use entity_attribute_transformers array within sync_config.config to specify attributes

Each integration supports different attributes and has different requirements. Refer to integration-specific documentation for required compared to optional attributes and formatting requirements.

See the CreateAccessRequest endpoint documentation and Quick Start Tutorial for integration-specific examples.

Integration-Specific Questions

Do you need SCIM to use Access Grant APIs

No, SCIM is just one option. Access Grant APIs work with any integration that supports Lifecycle Management Actions, including Active Directory, Okta, Azure AD, Snowflake, and others.

SCIM integrations are particularly useful when a target system does not have a native Veza integration but supports SCIM protocols for user and group management.

Can you manage access to multiple systems with one API call

Not directly, but you could:

• Use a SCIM gateway that federates to multiple downstream systems

• Automate multiple API calls in sequence for different target systems

• Create hierarchical Access Profiles in Veza to grant bundles of entitlements across systems

How do you authenticate to different target systems

Authentication is handled by your integration configuration, not the Access Grant API calls. Each integration type supports different authentication methods, for example:

• Active Directory: Service account credentials

• SCIM: Bearer tokens or OAuth2

• Cloud systems: API keys or service principal authentication

You must configure appropriate authentication when setting up your integration (not in the API requests).

Why do user attribute updates show "COMPLETED" but nothing changes on the target system

This can occur with some integrations, particularly SCIM integrations. In some cases, an integration can report success even when the target system rejects the update.

SCIM integration issues can include:

• SCIM protocol formatting errors in PATCH operations

• Missing required fields in SCIM update requests

Verification Steps:

1. Check your target system directly - Don't rely solely on the API response status

2. Look for error messages in the request details, even if the overall status is "COMPLETED"

3. Test with a different integration type (e.g., Active Directory) to confirm the API works correctly

Test thoroughly in development environments before production use, and verify the actual impact in downstream systems.

Why does my user update request fail with SCIM protocol errors

If you see errors mentioning missing 'path' fields or SCIM operation formatting issues, this indicates a problem with SCIM PATCH request formatting.

Common Error Messages:

• 'Field required', 'loc': ('body', 'Operations', 0, 'path')

• SCIM protocol formatting issues

• HTTP 422 status codes from the SCIM server

Workarounds:

1. Verify SCIM server compatibility - Ensure your SCIM server fully supports SCIM 2.0 PATCH operations

2. Test with minimal attributes - Start with only required fields to isolate the issue

3. Check SCIM server logs - Many SCIM servers provide detailed error logs showing exactly what was malformed

4. Use native integrations when available - If your system has a native Veza integration, use that instead of SCIM for better reliability

If you continue experiencing issues, contact Veza support with the complete error message and your SCIM server details for assistance.

SCIM Attributes

What SCIM attributes does Veza support

Veza supports SCIM 2.0 attributes for both read-only data extraction and Lifecycle Management synchronization. Specific attributes available depend on whether you are extracting data purely for Access Graph visibility and synchronizing user and group information, and if custom or extension attributes are enabled for the integration.

For the complete attribute reference with data types, requirements, and supported provisioning actions, see the SCIM integration guide.

Core User Attributes

For Attribute Synchronization, Veza supports the standard SCIM user attributes including:

• Identity & Authentication: userName (required), id, externalId, active

• Contact Information: emails, phoneNumbers, addresses, ims

• Personal Information: displayName, givenName, familyName, middleName, nickName

• Professional Information: title, userType, locale, timezone, preferredLanguage

For Read-Only Extraction, all SCIM core attributes are captured, including additional metadata such as profileUrl, photos, createdAt, and lastModified.

Group Attributes

Veza supports standard SCIM group attributes including displayName, id, externalId, groupType, description, and members for both extraction and AccessRequest operations.

Extension Attributes

Enterprise Extension Support: Veza can synchronize Enterprise Extension attributes including department, division, employeeNumber, costCenter, organization, and manager.

Custom Extensions: Veza can automatically discover and extract all custom vendor-specific SCIM extension attributes for read-only purposes (they appear in the Access Graph). You can synchronize Custom vendor extensions when Extension Schema Discovery is enabled, by referencing the normalized attribute name when constructing a transformer for Lifecycle Management or Access Requests.