Identity and Access Management (IAM) Events Guide

Overview

The Identity and Access Management (IAM) service sends notifications when any changes are made to entities within IAM. This documentation outlines how to view, interpret, and effectively work with these events.

Getting Started

Prerequisites

• Active subscription to IAM events (follow subscription instructions) to access Events endpoints.

Event Output Structure

• id: Uniquely identifies the event
• specversion: CloudEvents specification version (default 1.0)
• source: Organization/process that produced the event (/iam/environment/<appId>)
• dataschema: Schema that data adheres to
• datacontent type: Content type of the data
• data: Event Data Payload Attributes (within data field)
  • sourceTrn: Entity being created or modified
  • caller: Who initiated the action (users/applications/devices)
  • application: Application that made the request
  • targetTrn: Target entity for relationship operations
  • propertyKeys: Specific attributes that were changed
• type: Value describing the type of event related to the originating occurrence

Understanding Event Types

Event types in IAM indicate what kind of action triggered the event. They are categorized as follows:

Single Entity Operations: [action]_[entity]

These events represent actions performed on a single entity.

Examples:

• create_user: A new user was created
• update_account: An account was updated
• delete_group: A group was deleted

Relationship Operations: [action][source][target]

These events represent actions involving relationships between two entities.

Examples:

• add_user_account: A user was associated with an account
• delete_role_permission: A permission was removed from a role

How to Use This Reference

1. Identify the Action: Look at the event type to understand what happened
2. Find the Entities: Check sourceTrn and targetTrn to see what was affected
3. Check Changes: Use propertyKeys to see specific modifications
4. Track Relationships: Look for the relation object for association details

For association/dissociation events, check both sourceTrn and targetTrn:

• sourceTrn: The primary entity (e.g., user being added)
• targetTrn: The target entity (e.g., group receiving the user)

Note

For invitation-based events, a relation object may be present with invitation details like status and tracking IDs.

IAM Event Types List

User Events

• create_user: New user created
• update_user: User profile modified
• delete_user: User removed - Direct user removal endpoint is not available this event is triggered by internal operation like delete invitation

User Account Events

• add_user_account: User associated with the account
• update_user_account: User-account relationship modified - Any updates in the role of a user in account or invitation related events will be part of this event
• delete_user_account: User removed from account

Group Events

• create_group: New group created
• update_group: Group details updated
• delete_group: Group removed

Group User Events

• add_group_user: User added to group
• update_group_user: User-group relationship modified
• delete_group_user: User removed from group

Group Account Events

• add_group_account: Group associated with account
• update_group_account: Group-account relationship modified
• delete_group_account: Group removed from account

Application Events

• create_application: New application registered
• update_application: Application details updated
• delete_application: Application removed

Application Account Events

• add_application_account: Application associated with account
• delete_application_account: Application removed from account

Application Group Events

• add_application_group: Application associated with group
• update_application_group: Application-group relationship modified
• delete_application_group: Application removed from group

Permission Events

• create_permission: New permission created
• update_permission: Permission details updated
• delete_permission: Permission removed

Permission Application Events

• add_permission_application: Permission created using application
• delete_permission_application: Permission removed using application

Permission Group Events

• add_permission_group: Permission granted to group

Role Events

• create_role: New role created
• update_role: Role details updated
• delete_role: Role removed

Role Application Events

• add_role_application: Role associated with application
• delete_role_application: Role removed from application

Role Permission Events

• add_role_permission: Permission assigned to role
• delete_role_permission: Permission removed from role

Organization Events

• create_organization: New organization created

Organization Account Events

• add_organization_account: Account associated with organization

Organization Address Events

• add_organization_address: Address added to organization

Organization Enrichment Events

• add_organization_enrichment: Enrichment data added to organization

Device Events

• create_device: New device registered
• update_device: Device details updated
• delete_device: Device removed

Device Account Events

• add_device_account: Device associated with account
• update_device_account: Device-account relationship modified
• delete_device_account: Device removed from account

Device Group Events

• add_device_group: Device added to group
• update_device_group: Device-group relationship modified
• delete_device_group: Device removed from group

Device Certificate Events

• add_device_certificate: Certificate added to device
• delete_device_certificate: Certificate removed from device

Account Events

• create_account: New account created
• update_account: Account details updated
• delete_account: Account removed

Address Events

• create_address: New address created
• update_address: Address details updated
• delete_address: Address removed

Account External System Events

• create_accounts_external_systems: Account linked to external system
• update_accounts_external_systems: Account-external system link modified
• delete_accounts_external_systems: Account-external system link removed

Account Address Events

• create_accounts_addresses: Account linked to address
• update_accounts_addresses: Account-address link modified
• delete_accounts_addresses: Account-address link removed

Address External System Events

• create_addresses_external_systems: Address linked to external system
• update_addresses_external_systems: Address-external system link modified
• delete_addresses_external_systems: Address-external system link removed

Event Triggers

IAM events may not always be the direct result of API endpoint calls. Many events are triggered by internal system operations, background processes, or cascading effects from other actions. For example, a user deletion event might be triggered by an internal cleanup process rather than a direct API call to delete a user.

Filtering Specific Required Events

To filter specific required events, you can use the following curl command.

Example: Filter User Events

curl --location --request PUT '{base_url}/subscriptions/namespaces/com.trimble.tcp.iam/events/iam/versions/1/environments/{env}/filters' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "filter": {
    "criteria": "type",
    "fields": [
      {
        "key": "type",
        "value": "user"
      }
    ]
  }
}'

For Authorization

Use the same application token that you used for subscribing to IAM Events.

Reference

IAM Events Consumer Endpoints

Environment	Endpoint
Production	https://eventservice.events.trimblecloud.com/1.0/consumers/namespaces/com.trimble.tcp.iam/events/iam/1
Stage	https://preprd-eventservice.events.trimblecloud.com/1.0/consumers/namespaces/com.trimble.tcp.iam/events/iam/1