Release Notes

Quick Start

Step-by-step tutorial demonstrating the complete Access AuthZ workflow

This tutorial demonstrates the core Access Request API workflow through a practical SCIM integration example. You will:

  • Integrate Veza with a target system using SCIM-compliant APIs

  • Call Veza APIs to trigger granting or removal of entitlements (in this case, SCIM groups) to SCIM Users

  • Create users and modify attributes for existing users

You will also use APIs to configure system settings and get integration capabilities, request status, and Access Graph query results.

This covers the standard workflow from initial configuration through user creation and group management:

  1. Veza Environment Setup: Enable Access Requests and configure auto-approval

  2. Lifecycle Management Configuration: Enable provisioning on an existing integration

  3. User Creation: Use an Access Request and sync identities configuration to create accounts

  4. Entity Discovery: Query the Access Graph to find users and groups

  5. Relationship Management: Assign users to groups via Direct API

  6. Status Monitoring: Track request progress and completion

This guide demonstrates the complete workflow. For additional patterns and troubleshooting, see the FAQ and the endpoint documentation:

Prerequisites

Before starting, complete the Prerequisites and Setup guide.

Step 1: Identity the LCM datasource

List available LCM datasources:

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

Look for your integration in the response:

{
  "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"}
        ]
      }
    }
  ]
}

Save the id field for future requests.

Note: Some integrations include additional metadata in the response, such as supported attributes and required fields for SYNC_IDENTITIES actions. This information helps you construct valid entity_attribute_transformers for user creation requests.

Step 2: Create a user account

Create a new user account with the selected attributes using a direct Access Request:

curl -X POST "https://your-instance.vezacloud.com/api/private/lifecycle_management/access_requests" \
  -H "authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "GRANT",
    "request_source": "ACCESS_REQUEST",
    "reason": "Quickstart guide - creating test user",
    "datasource_id": "0198cfaf-1f97-7698-a760-05b98833ffd3",
    "assignee_entity_type": "OAA.SCIM.User",
    "sync_config": {
      "config": {
        "create_allowed": true,
        "continuous_sync": false,
        "entity_attribute_transformers": [
          {
            "destination_attribute": "user_name",
            "destination_value_formatter": "quickstart.test.user",
            "unique_identifier": true
          },
          {
            "destination_attribute": "display_name",
            "destination_value_formatter": "Quickstart Test User"
          },
          {
            "destination_attribute": "emails",
            "destination_value_formatter": "[email protected]"
          }
        ]
      }
    }
  }'

Attribute Update Behavior:

This same operation can update existing user attributes:

  • Set continuous_sync: true (config level) to enable updating existing active users

  • Set continuous_sync: true on individual attributes to update them on existing users

  • Attributes with continuous_sync: false only apply to new users

  • Inactive users (disabled/suspended) are always updated when reactivated

The API locates existing users by fields marked with unique_identifier: true.

Expected Response:

{
  "value": {
    "id": "0198cfaf-9e30-7b4b-bd88-6c1b9b94698a",
    "state": "PLAN_SELECTED",
    "request_type": "GRANT",
    "reason": "Quickstart guide - creating test user",
    "assignee_entity_type": "OAA.SCIM.User",
    "sync_config": {
      "config": {
        "create_allowed": true,
        "continuous_sync": false,
        "entity_attribute_transformers": [
          {
            "destination_attribute": "user_name",
            "destination_value_formatter": "quickstart.test.user",
            "unique_identifier": true
          },
          {
            "destination_attribute": "display_name",
            "destination_value_formatter": "Quickstart Test User"
          },
          {
            "destination_attribute": "emails",
            "destination_value_formatter": "[email protected]"
          }
        ]
      }
    }
  }
}

Save the request id to monitor progress.

Understanding sync_config: The sync_config parameter is used for SYNC_IDENTITIES actions (creating, updating, or reactivating user accounts). For relationship management (adding users to groups), use target_entity_ids without sync_config.

  • create_allowed: true - Creates new users if they don't exist

  • continuous_sync: true - Enables updating attributes on existing active users

  • unique_identifier: true - Marks fields used to locate existing users (cannot change after creation)

Step 3: Monitor request status

Check if your user creation has completed:

curl -X GET "https://your-instance.vezacloud.com/api/private/lifecycle_management/access_requests/0198cfaf-9e30-7b4b-bd88-6c1b9b94698a" \
  -H "authorization: Bearer YOUR_API_TOKEN"

When the job is successful, you will see:

{
  "value": {
    "id": "0198cfaf-9e30-7b4b-bd88-6c1b9b94698a",
    "state": "COMPLETED",
    "assignee_entity_id": "custom_provider:application:...:user:bc2bfa1c-4c13-4446-8402-76f74a371144",
    "assignee_entity_type": "OAA.SCIM.User",
    "completed_at": "2025-08-22T02:50:51.372691185Z",
    "error_message": ""
  }
}

Important for automation: When creating a new user with sync_config, the assignee_entity_id field is automatically populated after the user is created. This ID is typically used for follow-up operations such as assigning the user to groups (as shown in Step 6). You can use this value in future API calls without needing to query the Access Graph.

Possible states:

  • INITIAL - Request has been created

  • WAITING_FOR_APPROVAL - Request awaiting approval

  • NEEDS_MORE_INFORMATION - Approver requested more information

  • PLAN_SELECTED - Request is processing

  • COMPLETED - Request completed successfully

  • ERRORED - Check error_message field for details

  • REJECTED - Request was rejected

  • CANCELED - Request was canceled

  • JIT_REVOKED - Just-in-time access was revoked

  • EXTERNAL_RUNNING - External system is processing request

Step 4: Find available groups

Query for groups you can assign the user to using the Access Graph:

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": "OAA.SCIM.Group"
        }
      ]
    }
  }'

Look for groups in the response:

{
  "values": [
    {
      "id": "custom_provider:application:...:group:a40d16d5-7baa-4152-bc7a-664840603454",
      "type": "OAA.SCIM.Group",
      "properties": {
        "name": "Test Group 001"
      }
    }
  ],
  "next_page_token": "",
  "has_more": false
}

Query your SCIM server directly to discover the latest groups, as the Veza Access Graph can take time to sync and might not reflect recent changes. Direct SCIM queries ensure you have the most up-to-date group information for your Access Requests.

Step 5: Query for the created user

Find your newly created user's Access Graph ID:

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": "OAA.SCIM.User"
        }
      ]
    }
  }'

Find the user by name in the response:

{
  "values": [
    {
      "id": "custom_provider:application:...:user:bc2bfa1c-4c13-4446-8402-76f74a371144",
      "type": "OAA.SCIM.User",
      "properties": {
        "name": "Quickstart Test User",
        "customprop_user_name": "quickstart.test.user"
      }
    }
  ],
  "next_page_token": "",
  "has_more": false
}

Step 6: Assign user to group

Add your user to a group using the direct Access Request API:

curl -X POST "https://your-instance.vezacloud.com/api/private/lifecycle_management/access_requests" \
  -H "authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "GRANT",
    "request_source": "ACCESS_REQUEST",
    "reason": "Quickstart guide - adding user to group",
    "datasource_id": "0198cfaf-1f97-7698-a760-05b98833ffd3",
    "assignee_entity_type": "OAA.SCIM.User",
    "assignee_entity_id": "custom_provider:application:...:user:bc2bfa1c-4c13-4446-8402-76f74a371144",
    "target_entity_type": "OAA.SCIM.Group",
    "target_entity_ids": ["custom_provider:application:...:group:a40d16d5-7baa-4152-bc7a-664840603454"]
  }'

Expected Response:

{
  "value": {
    "id": "0198cfb4-0adb-740b-8e2d-7a7c09044996",
    "state": "PLAN_SELECTED",
    "request_type": "GRANT",
    "assignee_entity_name": "Quickstart Test User",
    "target_entity_names": ["Test Group 001"],
    "entitlements": [
      {
        "entity_type": "OAA.SCIM.Group",
        "entity_id": "custom_provider:application:...:group:a40d16d5-7baa-4152-bc7a-664840603454"
      }
    ]
  }
}

Monitor this request using the same method as Step 3.

Step 7: Remove user from group (Optional)

To finish testing the grant/revoke cycle, you can remove the user from the group:

curl -X POST "https://your-instance.vezacloud.com/api/private/lifecycle_management/access_requests" \
  -H "authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "REVOKE",
    "request_source": "ACCESS_REQUEST",
    "reason": "Quickstart guide - removing user from group",
    "datasource_id": "0198cfaf-1f97-7698-a760-05b98833ffd3",
    "assignee_entity_type": "OAA.SCIM.User",
    "assignee_entity_id": "custom_provider:application:...:user:bc2bfa1c-4c13-4446-8402-76f74a371144",
    "target_entity_type": "OAA.SCIM.Group",
    "target_entity_ids": ["custom_provider:application:...:group:a40d16d5-7baa-4152-bc7a-664840603454"]
  }'

Expected Response:

{
  "value": {
    "id": "0198cfb4-dff5-7acf-a3ee-165bb2cda52c",
    "state": "PLAN_SELECTED",
    "request_type": "REVOKE",
    "assignee_entity_name": "Quickstart Test User",
    "target_entity_names": ["Test Group 001"]
  }
}

After the request completes (state: "COMPLETED"), verify in your SCIM server that the user has been removed from the group's members array.

Verification

Check the target application

Veza's Access Graph will not refresh until the next scheduled extraction, or you manually trigger an extraction. You can trigger an extraction in Veza by opening the integration details and clicking Start Extraction on the Data Sources tab.

In this example, we query the SCIM server to confirm the changes.

Verify the changes were made in your target system:

# Check if user was created
curl -X GET "http://your-scim-server/Users" \
  -H "Authorization: Bearer YOUR_SCIM_TOKEN"

Look for the user in the response:

{
  "totalResults": 1,
  "Resources": [
    {
      "id": "bc2bfa1c-4c13-4446-8402-76f74a371144",
      "userName": "quickstart.test.user",
      "displayName": "Quickstart Test User",
      "active": true,
      "emails": [{"value": "[email protected]"}],
      "meta": {
        "resourceType": "User",
        "lastModified": "2025-08-22T02:50:51.252263"
      }
    }
  ]
}

Verify the user attributes match the request:

  • userName should match your destination_value_formatter for user_name

  • displayName should match your destination_value_formatter for display_name

  • emails should contain your specified email address

  • active: true confirms the user is enabled

Check group members for assigned users:

# Check if user was added to group
curl -X GET "http://your-scim-server/Groups/GROUP_ID" \
  -H "Authorization: Bearer YOUR_SCIM_TOKEN"

The response should show:

{
  "id": "a40d16d5-7baa-4152-bc7a-664840603454",
  "displayName": "Test Group 001",
  "members": [
    {
      "value": "bc2bfa1c-4c13-4446-8402-76f74a371144",
      "display": "Quickstart Test User",
      "$ref": "/Users/bc2bfa1c-4c13-4446-8402-76f74a371144"
    }
  ],
  "meta": {
    "lastModified": "2025-08-22T02:55:41.035765"
  }
}

  • The members array contains an entry with your user's ID

  • display matches your user's display name

  • The lastModified timestamp shows recent changes (after your API call)

  • $ref provides the direct link to the SCIM user resource

Troubleshooting:

  • If verification fails, check the Access Request state for errors

  • Unexpected attributes can indicate issues with entity_attribute_transformers values

  • Empty members arrays indicate that a group assignment has failed

  • lastModified timestamp can indicate when an operation may not yet be complete

Check request history

List all your access requests to see the complete history:

curl -X GET "https://your-instance.vezacloud.com/api/private/lifecycle_management/access_requests?page_size=10" \
  -H "authorization: Bearer YOUR_API_TOKEN"

You have now completed the Access Request API example workflow!

Next steps

PreviousAccess AuthZ APIsNextPrerequisites

Last updated

Was this helpful?