Security Best Practices

This guide covers security best practices for generating and managing User Tokens in the Licensing API, following Zero Trust principles and the principle of least privilege.

Overview

User Tokens are UUID-based identifiers that enable programmatic access to the Licensing API, designed for application integrations and automated systems. They follow a two-stage authentication process:

1. User Token → Exchange for temporary access token
2. Access Token → Used for API requests (24-hour expiration)

Zero Trust Model

Least Privilege

Always grant the minimum permissions necessary for your application to function. This reduces the attack surface and limits potential damage if a token is compromised.

Key Guidelines

• Start with no permissions and add only what's required
• Regularly audit and remove unused permissions
• Use specific actions rather than broad roles when possible
• Implement time-bounded access where appropriate

Permission Model

Each User Token has specific permissions assigned directly to it, providing granular control over what actions the token can perform.

Permission Assignment

• Permissions are assigned directly to User Tokens during creation
• This ensures maximum security and clarity about token capabilities

Token Generation

1. Identify Required Permissions

Before creating a User Token, determine the exact permissions your application needs:

For Read-Only Integrations:

• View Users - List and retrieve user information
• View Products - Access product and plan data
• View Licenses - Read license information

For License Management:

• View Licenses - Read license data
• Edit Licenses - Modify license status/attributes
• View Customers - Access customer information

For User Administration:

• View Users - List users
• Create Users - Add new users
• Edit Users - Modify user attributes
• Edit User Tokens - Refresh user tokens

2. Permission Assignment

User Tokens use direct permission assignment. During token creation through the web application, you assign specific permissions directly to the token:

User Token Permissions:
  - View Users
  - View Licenses
  - View Products

Best Practice: Only assign the minimum permissions required for your specific use case.

3. Token Creation Process

User Tokens are created exclusively through the web application interface by authorized administrators.

Step-by-Step Token Creation

1. Log into the web application with appropriate permissions
2. Navigate to the Users section
3. Create a new User Token
4. Assign the specific permissions required for your use case
5. The system automatically generates a UUID token

Security Requirements

After Token Creation:

• Retrieve the token through the web interface
• Store token securely using environment variables or secure configuration management
• Never commit tokens to version control
• Establish a regular token rotation schedule

Permission Categories

User Management

• View Users - List and retrieve user information
• Create Users - Add new users to the system
• Edit Users - Modify user attributes and roles
• Delete Users - Remove users from the system
• Edit User Tokens - Refresh user tokens

Product & License Management

• View Products - Access product and plan information
• Edit Products - Modify product attributes
• View Licenses - Read license data and status

Group Management

• Create Groups - Create new user groups
• Edit Groups - Modify group settings and membership
• Delete Groups - Remove groups from the system

Common Use Cases

Read-Only Integration

Use Case: External system needs to fetch user and license data Deployment: Server-side integration Token Creation: Create User Token through web app with permissions:

• View Users
• View Licenses
• View Products

License Provisioning

Use Case: Automated system that creates and manages licenses Deployment: Server-side integration Token Creation: Create User Token through web app with permissions:

• View Users
• View Licenses
• View Customers
• Edit Licenses (if license modification is required)

User Onboarding

Use Case: HR system that creates users in the licensing platform Deployment: Server-side integration Token Creation: Create User Token through web app with permissions:

• View Users
• Create Users
• View Products (to assign appropriate licenses)

Client Application License Validation (Client-Side)

Use Case: Desktop or mobile app that needs to validate licenses Deployment: Client-side integration (high risk) Recommended Approach: Use license key endpoints (/v1/licenses/validate) instead of User Tokens Alternative: If User Token required, create through web app with minimal permissions:

• View Licenses (only if absolutely necessary)

Monitoring & Analytics (Server-Side)

Use Case: Dashboard or reporting system Deployment: Server-side integration Token Creation: Create User Token through web app with permissions:

• View Users
• View Licenses
• View Products

Deployment Scenarios

Server-Side Integration (Recommended)

Use Case

Backend services, server applications, automated systems

Security Characteristics

• Tokens stored securely on servers (environment variables, key management systems)
• No exposure to end users or client-side code
• Full access to assigned permissions
• Standard token-based authentication flow

Best Practices

• Store tokens in secure server environments
• Implement proper error handling and retry logic
• Use HTTPS for all communications
• Monitor token usage patterns

Client-Side Integration (High Risk)

Use Case: Desktop applications, mobile apps where tokens might be accessible to end users

Security Risks

• Tokens may be extractable by end users
• Potential for token abuse or sharing
• Limited ability to secure token storage
• Higher risk of unauthorized access

Mitigation Strategies

• Use most restrictive permissions possible
• Implement additional client-side security measures
• Consider alternative authentication methods where possible
• Monitor for unusual usage patterns
• Implement shorter token rotation cycles

License Key Endpoints (Token-Free)

For scenarios where User Token security cannot be guaranteed, certain endpoints operate with license keys only:

Available Endpoints:

POST /v1/licenses/validate

Validate license status using license key only - no access token required.

When to Use:

• Client applications where token security is a concern
• Public-facing integrations
• Scenarios requiring only license validation

Implementation

Access Tokens

User Tokens exchange for access tokens with these characteristics:

• Expiration: 24 hours
• Refresh: Automatic via refresh tokens
• Scope: Limited to assigned permissions

Tenant Isolation

All tokens are scoped to specific tenants:

• Tokens cannot access data from other tenants
• Multi-tenant applications require separate tokens per tenant

Rate Limiting

The system implements license-based rate limiting:

• Requests are tracked against tenant license limits
• Exceeded limits result in HTTP 429 responses
• Plan your API usage within license constraints

Token Refresh

For Long-Running Applications:

• Implement automatic token refresh when receiving 401 responses
• Store refresh tokens securely
• Handle refresh failures gracefully

For Short-Lived Scripts:

• Consider using fresh tokens for each execution
• Implement proper error handling for token failures

Monitoring

Usage Tracking

• Monitor API request patterns for unusual activity
• Set up alerts for failed authentication attempts

Token Rotation

1. Quarterly Review: Audit all active User Tokens
2. Permission Cleanup: Remove unused permissions
3. Token Refresh: Generate new tokens for active integrations
4. Deactivation: Remove tokens for discontinued integrations

Incident Response

Token Compromise Response

If a token is compromised:

1. Immediate: Refresh the User Token to invalidate all access tokens
2. Remediation: Update token permissions if over-privileged
3. Prevention: Review storage and handling practices

Error Handling

Error Scenarios

Invalid Token (401):

{
  "error": "Invalid token"
}

Solution: Refresh the User Token or verify token accuracy

Insufficient Permissions (403):

{
  "error": "Access denied"
}

Solution: Review and add required permissions to the user

License Limit Exceeded (429):

{
  "error": "Too Many Requests (Reached license limit)"
}

Solution: Optimize request patterns or upgrade license

Expired License:

{
  "error": "Invalid license"
}

Solution: Renew tenant license

Checklists

Server-Side

Security Requirement
Token has minimum required permissions only
Token is stored securely (environment variables, not code)
Application handles token refresh automatically
Error handling is implemented for all auth scenarios
Token usage is monitored and audited
Regular token rotation schedule is established
Emergency token revocation process is documented
Permissions are reviewed quarterly
Multi-tenant applications use separate tokens per tenant
Rate limiting constraints are considered in application design

Client-Side

Security Requirement
Most restrictive permissions assigned (minimal access)
Consider license key endpoints for validation-only scenarios
Implement additional application-level security controls
Shorter token rotation cycles established
Enhanced monitoring for unusual usage patterns
Clear user communication about token security
Regular security assessment of client-side token exposure
Incident response plan for compromised client tokens

Additional Considerations

Network Security

• Use HTTPS for all API communications
• Implement proper TLS certificate validation
• Consider IP restrictions if feasible

Application Security

• Validate all API responses before processing
• Implement proper logging without exposing tokens
• Use secure coding practices for token handling

---

Summary

By following these security best practices, you can ensure that your User Token implementation provides secure access to your applications while maintaining Zero Trust principles.