API Users Management
What are API Users?
API Users are special system accounts designed specifically for programmatic access to OSPROV workflows. Think of them as "robot users" that represent external systems, applications, or automated processes rather than human users.
Key Characteristics
- System Accounts: Represent systems, not people
- Token Authentication: Use 80-character API tokens instead of passwords
- No Web Access: Cannot log into the OSPROV web interface
- Role-Based: Have specific API-related permissions and roles
- Audit Tracked: All actions are logged for compliance and monitoring
Creating API Users
Admin Access Required: Only system administrators can create API Users through:
- Navigate to Admin → API Users
- Click "Create New"
- Fill required information:
- Name: Descriptive identifier (e.g., "SAP HR Integration", "Mobile App API")
- Email: Unique email address (used as identifier)
- Status: Active/Inactive toggle
- Roles: Typically "Service-Account" + "Applicant"
- System generates automatically:
- 80-character API token for authentication
- Username (same as email)
- Guard name set to 'api'
API User Properties
| Property | Description | Example |
|---|---|---|
| Name | Descriptive identifier for the integration | "HR System Integration" |
| Unique identifier | "hr-api@company.com" | |
| API Token | 80-character authentication token | "abc123...xyz789" |
| Status | Active/Inactive | Active |
| Roles | Permissions assigned | Service-Account, Applicant |
| Last Login | Last API request timestamp | 2024-01-15 10:30:00 |
Managing API Users
Viewing API Users
- List View: All API users with status, roles, and activity
- Detail View: Complete information including creation history
- Usage Analytics: Request counts, success rates, error patterns
Editing API Users
- Update name, email, status, and roles
- Cannot directly edit API tokens (must regenerate)
- All changes are tracked in audit logs
Token Management
- View Token: Safely display current token (usually masked)
- Regenerate Token: Create new token (immediately invalidates old one)
- Security: Treat tokens like passwords - store securely
- Rotation: Regenerate periodically for security
Security and Permissions
- Default Roles: Service-Account + Applicant roles for basic API access
- Custom Roles: Create specific roles for different integration needs
- Permission Control: Fine-grained control over workflow access
- Rate Limiting: Built-in limits prevent abuse (configurable via environment)
Common API User Examples
| Integration Type | API User Name | Purpose |
|---|---|---|
| ERP System | "SAP-ERP-Integration" | Purchase orders, financial approvals |
| HR System | "HR-System-API" | Employee onboarding, leave requests |
| Mobile App | "FieldWorker-Mobile-App" | Field inspections, maintenance reports |
| IoT Sensors | "IoT-Monitoring-System" | Equipment alerts, environmental monitoring |
| Customer Portal | "Customer-Portal-API" | Service requests, support tickets |
| Batch Processing | "Nightly-Batch-Service" | Bulk application processing |
Best Practices
Naming Conventions
- Use descriptive names that indicate the source system
- Include purpose or department (e.g., "Finance-ERP-Integration")
- Avoid generic names like "API User 1"
Security Management
- Minimal Permissions: Only assign necessary roles and permissions
- Regular Audits: Review API users periodically, deactivate unused ones
- Token Security: Store tokens in secure configuration management
- Monitor Usage: Track API activity for unusual patterns
Lifecycle Management
- Documentation: Keep records of what each API User is for
- Ownership: Assign responsibility for each integration
- Deactivation: Disable rather than delete when no longer needed
- Cleanup: Regularly review and remove obsolete integrations
Troubleshooting API Users
Common Issues
- Authentication Failures: Check token validity and user status
- Permission Denied: Verify roles and workflow-specific permissions
- Rate Limits: Monitor usage against configured limits
- Inactive Users: Ensure API User status is set to active
Monitoring and Analytics
- Usage Tracking: Monitor API request volumes and patterns
- Error Analysis: Identify common failure points
- Performance Metrics: Track response times and success rates
- Audit Compliance: Maintain logs for regulatory requirements
The API Users system provides a secure, manageable way to enable system-to-system integration while maintaining clear separation from human user accounts and comprehensive audit trails.