Skip to main content

Managing Users with Fiscus

Fiscus provides a robust system for user management, enabling developers to handle users, connectors, and access control dynamically. Through the FiscusUser class, you can manage everything from user-specific context, authentication, role-based access control (RBAC), and dynamic preferences, all while maintaining audit trails for every action taken.

Overview of FiscusUser​

The FiscusUser class is central to managing users and their interactions with connectors and APIs. Each user in Fiscus has unique attributes, roles, and policies that define how they interact with the system. Below are the key capabilities offered by the FiscusUser class:

Key Features:​

  • Connector Management: Add, remove, authenticate, and manage connectors for each user.
  • Context Management: Set and retrieve user-specific context variables to personalize workflows.
  • Dynamic Preferences: Customize API behavior through user-specific preferences.
  • Role-Based Access Control (RBAC): Assign roles and policies to control which APIs and operations users can access.
  • Audit Trails: Record every user action, from adding connectors to changing context.

Example: Initializing a User​

To start managing users in Fiscus, you first need to initialize a FiscusUser instance with a unique user_id. This user_id allows Fiscus to track all activities related to this user.

from fiscus import FiscusUser, FiscusClient

# Initialize FiscusClient
client = FiscusClient(api_key='YOUR_FISCUS_API_KEY')

# Create a FiscusUser instance
user = FiscusUser(user_id='user_123', client=client)

Example Breakdown:​

  1. FiscusClient Initialization: This client is responsible for managing operations and workflows.
  2. FiscusUser Initialization: The user_id uniquely identifies the user and links their activities, preferences, and connectors.

Connector Management​

Each FiscusUser can manage multiple connectors. Connectors represent external APIs or services the user interacts with, such as Gmail, Salesforce, or custom APIs. Users can add connectors, authenticate them, and remove them as needed.

Example: Adding and Authenticating a Connector​

You can add a connector to a user and authenticate it with the following:

from fiscus import FiscusUser, FiscusClient

# Initialize FiscusClient and FiscusUser
client = FiscusClient(api_key='YOUR_FISCUS_API_KEY')
user = FiscusUser(user_id='user_123', client=client)

# Add and authenticate a Gmail connector
user.add_connector('Gmail')
user.authenticate_connector('Gmail', auth_params={
    'access_token': 'YOUR_ACCESS_TOKEN',
    'refresh_token': 'YOUR_REFRESH_TOKEN'
})

How It Works:​

  1. Adding a Connector: The add_connector method adds a new API connection for the user, allowing them to interact with that service.
  2. Authentication: Once added, you must authenticate the connector by passing in the necessary authentication details (e.g., OAuth tokens).

Example: Listing All Connectors​

To list all connectors the user is currently managing:

connectors = user.list_connected_connectors()
print(connectors)

Example Output:​

  • Result: ['Gmail', 'Salesforce']
  • This confirms the user is connected to Gmail and Salesforce.

Context Management​

Fiscus allows you to set and retrieve user-specific context variables that can influence workflows and operations. Context variables are stored per user and can be dynamically referenced in policies, conditions, and workflow steps.

Example: Setting and Retrieving Context​

from fiscus import FiscusUser

# Set context
user.set_context('preferred_language', 'en')

# Retrieve context
preferred_language = user.get_context('preferred_language')
print(preferred_language)  # Output: 'en'

Use Case:​

  • Context: A variable like preferred_language can determine which version of an email template is sent or which API endpoint is used.

Dynamic Preferences​

Dynamic preferences allow for the customization of connector behavior based on user settings. These preferences are specific to the user and can be used to adjust how APIs respond or behave.

Example: Setting Dynamic Preferences​

user.set_dynamic_preferences({
    'email_format': 'HTML',
    'timezone': 'PST'
})

Example Breakdown:​

  • Dynamic Preferences: These preferences could be used to format emails as HTML for this specific user, or to ensure that API responses respect the user's time zone.

Role-Based Access Control (RBAC)​

Fiscus supports role-based access control, allowing you to assign specific roles to users and define policies that govern which connectors and operations they can access. Policies allow you to enforce fine-grained access control based on roles, conditions, and API operations.

Example: Assigning Roles and Policies​

You can assign roles to users and add policies that define what they can access.

from fiscus import FiscusUser

# Assign a role to the user
user.assign_role('admin')

# Add a policy for API access
policy = {
    'roles': ['admin'],
    'connectors': ['Gmail', 'Salesforce'],
    'operations': ['send_email', 'create_contact']
}
user.add_policy(policy)

How It Works:​

  1. Roles: Roles define the level of access a user has (e.g., 'admin', 'user', 'guest').
  2. Policies: Policies define the specific connectors and operations that are permitted for each role, and can include conditions like context or dynamic preferences.

Example: Checking User Permissions​

To check if a user has permission to perform a specific operation:

if user.has_permission('Gmail', 'send_email'):
    print("Permission granted")
else:
    print("Permission denied")

Example Breakdown:​

  • Permission Check: This will return True or False based on the user's roles and the policies associated with those roles.

Managing Audit Trails​

Every action taken by the user is automatically recorded in an audit trail. This includes actions like adding connectors, setting context, and executing API operations. You can access the audit trail to track and review user activity for security, debugging, or compliance purposes.

Example: Recording and Accessing Audit Logs​

# Record an action
user.add_connector('Gmail')

# Access audit logs
audit_logs = user.audit_trail.get_records()
for log in audit_logs:
    print(log)

Example Output:​

{'action': 'add_connector', 'details': {'connector_name': 'Gmail'}, 'timestamp': '2024-10-01T12:00:00Z'}

Use Case:​

Audit trails are especially useful for tracking API usage, debugging complex workflows, and ensuring compliance with security policies.

Changing User ID​

If needed, you can change the user_id of a FiscusUser instance. This is useful in scenarios where a user’s identifier needs to be updated (e.g., after merging accounts).

Example: Changing User ID​

# Change user ID
user.set_user_id('new_user_456')

### Example Breakdown:
- **Audit Logging**: The audit trail will log the change, ensuring that you can track the update from the old user ID to the new one.

Summary of User Management Capabilities​

  • Connector Management: Add, remove, and authenticate user-specific connectors for any API.
  • Context and Preferences: Use context and dynamic preferences to influence API behavior and workflows.
  • Role-Based Access Control: Assign roles and create policies to control access to connectors and operations.
  • Audit Trails: Automatically record all actions for security, debugging, and compliance.
  • User Flexibility: Change user identifiers and adapt user management in real time.

The FiscusUser class provides a flexible and powerful system for managing users and their API interactions. Whether you're building a simple app or orchestrating complex, multi-user workflows, Fiscus offers the tools you need to handle user-specific logic, authentication, and security with ease.