Security and auth models
These models manage user authentication, authorization, API access, and security controls in Chargeworx.UserInvitation
Manages user invitation workflow for onboarding new team members.Key properties
| Property | Type | Description |
|---|---|---|
| Id | Guid | Unique invitation identifier |
| String | Invitee email address | |
| CompanyId | Guid | Associated company reference |
| InvitedBy | Guid | User who sent invitation |
| Role | String | Assigned role |
| Status | String | Invitation status |
| Token | String | Unique invitation token |
| ExpiresAt | DateTime | Invitation expiration |
| CreatedAt | DateTime | Invitation creation timestamp |
| AcceptedAt | DateTime? | Acceptance timestamp |
Relationships
- Belongs to a Company
- References inviting User
Status values
| Status | Description |
|---|---|
| Pending | Invitation sent, awaiting acceptance |
| Accepted | User accepted and registered |
| Expired | Invitation expired |
| Cancelled | Invitation cancelled by admin |
WhitelistIp
Manages IP address whitelisting for enhanced API security.Key properties
| Property | Type | Description |
|---|---|---|
| Id | Guid | Unique identifier |
| CompanyId | Guid | Associated company reference |
| ProjectId | Guid? | Optional project-specific whitelist |
| IpAddress | String | Whitelisted IP address or CIDR range |
| Description | String | IP address description |
| IsActive | Boolean | Whitelist entry active status |
| CreatedAt | DateTime | Creation timestamp |
| CreatedBy | Guid | User who created entry |
Relationships
- Belongs to a Company
- Optionally belongs to a Project
IP formats
- Single IP:
192.168.1.100 - CIDR range:
192.168.1.0/24 - IPv6:
2001:0db8:85a3::8a2e:0370:7334
Key / CompanyProjectKey
Manages API keys for programmatic access to Chargeworx.Key
Base API key entity.| Property | Type | Description |
|---|---|---|
| Id | Guid | Unique key identifier |
| KeyValue | String | API key value (hashed) |
| KeyType | String | Key type (Public, Secret) |
| IsActive | Boolean | Key active status |
| CreatedAt | DateTime | Key creation timestamp |
| ExpiresAt | DateTime? | Optional expiration |
| LastUsedAt | DateTime? | Last usage timestamp |
CompanyProjectKey
Links API keys to specific company projects with permissions.| Property | Type | Description |
|---|---|---|
| Id | Guid | Unique identifier |
| KeyId | Guid | Associated key reference |
| CompanyId | Guid | Associated company |
| ProjectId | Guid | Associated project |
| Permissions | String | JSON array of permissions |
| Environment | String | Environment (Production, Sandbox) |
Relationships
- Key has many CompanyProjectKeys
- CompanyProjectKey belongs to Company and Project
Key types
- Public key - Used for client-side operations
- Secret key - Used for server-side API calls
- Restricted key - Limited permissions for specific operations
Usage patterns
User invitations
Admins invite new users by email. Invitations include a unique token and expire after a configured period (typically 7 days).IP whitelisting
Companies can restrict API access to specific IP addresses or ranges. Requests from non-whitelisted IPs are rejected.API key management
API keys are generated per project and can be scoped to specific permissions. Keys can be rotated or revoked as needed.Key rotation
Best practice is to rotate API keys periodically:- Generate new key
- Update applications to use new key
- Deactivate old key after transition period
Security best practices
- Rotate API keys regularly (every 90 days recommended)
- Use IP whitelisting for production environments
- Assign minimum required permissions to API keys
- Monitor key usage for suspicious activity
- Expire unused keys automatically
- Never commit API keys to source control
- Use separate keys for different environments
Audit and monitoring
- All API key usage is logged
- Failed authentication attempts are tracked
- IP whitelist violations are logged and alerted
- Invitation acceptance is audited
- Key rotation events are recorded