Data Collector API Requirements

Data Collector API Requirements (Required for User Login Information in UAR Campaigns)

Overview

To enable the Data Collector to retrieve user login information for use in User Access Review (UAR) campaigns, your API must provide comprehensive user data that allows for efficient reconciliation and access reviews.

---

Required API Response Fields

Your API endpoint must return the following fields for each user:

1. ExternalUserId

• Description: Unique identifier for the user
• Format: Email address or User Principal Name (UPN) where possible
• Fallback: If email/UPN is not available, use the local ID from your system
• Example: john.smith@company.com or jsmith123

2. UserDisplayName

• Description: Human-readable name of the user
• Format: Full name (First name + Last name)
• Example: John Smith

3. RoleName

• Description: The role assigned to the user
• Important: The API should return one row per user role
  • If a user has 2 roles, the API response will contain 2 separate rows for that user
  • Each row represents a unique user-role combination
• Example: System Administrator, Finance Manager, Sales Representative

4. LastLoginAt

• Description: Timestamp of the user’s last login
• Format: ISO 8601 format
• Example: 2026-05-05T14:30:00Z or 2026-05-05T14:30:00+00:00

5. Email (Optional)

• Description: User’s email address
• Format: Valid email address
• Use Case: Useful for matching when using a local ID in the ExternalUserId field
• Example: john.smith@company.com

---

Example API Response

[
  {
    "externalUserId": "john.smith@company.com",
    "userDisplayName": "John Smith",
    "roleName": "System Administrator",
    "lastLoginAt": "2026-05-04T09:15:00Z",
    "email": "john.smith@company.com"
  },
  {
    "externalUserId": "john.smith@company.com",
    "userDisplayName": "John Smith",
    "roleName": "Security Auditor",
    "lastLoginAt": "2026-05-04T09:15:00Z",
    "email": "john.smith@company.com"
  },
  {
    "externalUserId": "jane.doe@company.com",
    "userDisplayName": "Jane Doe",
    "roleName": "Finance Manager",
    "lastLoginAt": "2026-05-03T16:45:00Z",
    "email": "jane.doe@company.com"
  }
]

---

API Endpoint Configuration

Authentication

Ensure your API endpoint supports secure authentication methods such as:

• API Key: Include in request headers
• OAuth 2.0: Bearer token authentication
• Basic Auth: Username and password (over HTTPS only)

Endpoint Requirements

• Method: GET or POST
• Response Format: JSON
• HTTPS: Required for secure data transmission
• Rate Limiting: Consider implementing appropriate rate limits

---

Best Practices

• Data Completeness: Ensure all required fields are populated for each user-role combination
• Data Freshness: Keep user login data up-to-date; consider real-time or near-real-time synchronization
• Error Handling: Implement proper error responses (4xx/5xx status codes) with meaningful error messages
• Pagination: For large datasets, implement pagination to improve performance
• Monitoring: Monitor API usage and performance to ensure reliability during UAR campaigns

---

Benefits of Comprehensive User Data

Having complete and accurate user data enables:

• Efficient Reconciliation: Match users across different systems quickly and accurately
• Accurate Access Reviews: Ensure reviewers have all necessary information to make informed decisions
• Role-Based Analysis: Understand access patterns by role and identify potential security risks
• Activity Tracking: Use last login data to identify inactive accounts and stale access