Skip to main content

Connector Management for Users

In modern applications where multiple APIs are involved, managing connectors for each user is crucial to ensure they have the right access to external services. The Fiscus SDK provides a comprehensive framework for adding, removing, and authenticating connectors at a user level. This allows developers to manage external integrations dynamically, personalize workflows, and ensure secure, scalable access to various services based on individual user needs.

Adding Connectors for Users​

Adding connectors for users is the first step in enabling them to interact with specific APIs. In the Fiscus SDK, a connector is a service like Gmail, Salesforce, or any other API. Once a connector is added for a user, the user can execute operations against that service.

Use Case: Why Add Connectors?​

  • Personalized Access: In applications such as CRMs, email platforms, or financial tools, different users often need access to different services.
  • Scalability: Instead of a fixed set of APIs for all users, connectors can be dynamically added to users based on their roles, preferences, or subscriptions.
  • Security and Control: By adding connectors at the user level, you limit exposure and give fine-grained control over who can access what services.

How to Add a Connector​

To add a connector for a user, use the add_connector method. This method automatically configures the connector for the user and prepares it for any operations they may need to perform.

Example: Adding a Gmail Connector​

Add a Gmail connector for the user:

user.add_connector('Gmail')

Example: Adding a Salesforce Connector​

Add a Salesforce connector for the user:

user.add_connector('Salesforce')

Error Handling During Addition​

If the connector has already been added to the user, Fiscus will not add it again and will log a warning. This prevents unnecessary duplication or conflicts.

Handling connector duplication:​

user.add_connector('Gmail')

If Gmail was already added, logs a warning and skips adding

Once the connector is added, it's ready for use. However, if the connector requires authentication, you may need to handle that step next.

 

Removing Connectors for Users​

Removing connectors is an important aspect of managing user access. Users may no longer need access to certain services, or they may switch between services over time. By removing connectors that are no longer needed, you ensure that the system stays lean, secure, and efficient.

Use Case: Why Remove Connectors?​

  • Resource Optimization: Unused connectors can introduce unnecessary overhead. Removing them reduces the system's footprint and potential security risks.
  • Compliance: When users no longer need access to specific services (e.g., due to changing roles or subscription levels), connectors should be removed to comply with security best practices.
  • User Customization: Users may choose to connect and disconnect services based on their current needs, such as adding an email connector when sending emails but removing it afterward.

How to Remove a Connector​

To remove a connector from a user, you can use the remove_connector method. This method unregisters the connector from the user's account and clears its associated configuration and tokens.

Example: Removing a Gmail Connector​

Remove a Gmail connector for the user:

user.remove_connector('Gmail')

Example: Removing a Salesforce Connector​

Remove a Salesforce connector for the user:

user.remove_connector('Salesforce')

Error Handling During Removal​

If you attempt to remove a connector that isn't associated with the user, the Fiscus SDK will log a warning to indicate that the connector wasn’t found. This prevents errors and ensures that the system remains stable.

Handling missing connectors:​

user.remove_connector('Gmail')

If Gmail wasn't added to this user, logs a warning

 

Authenticating Connectors​

Most connectors will require authentication before they can be used. The Fiscus SDK supports various authentication mechanisms, including API keys, OAuth flows, and token-based systems. The SDK abstracts away much of the complexity, allowing you to securely manage user-specific authentication processes.

Use Case: Why Authenticate Connectors?​

  • Secure Access: Many services (e.g., Gmail, Salesforce, QuickBooks) require users to authenticate before allowing operations. Authentication ensures that only authorized users can interact with the service.
  • Token Management: Managing tokens (such as OAuth tokens) for users ensures seamless access to third-party services, even when tokens need to be refreshed.
  • Personalization: Different users will authenticate with their own credentials, ensuring that API calls are scoped to their individual accounts.

How to Authenticate a Connector​

You can authenticate a connector either manually by providing credentials, or programmatically by setting an authentication callback.

Example: Manual Authentication​

To manually authenticate a connector, pass the required credentials in the authenticate_connector method.

Authenticate Gmail connector using client_id and client_secret:

user.authenticate_connector('Gmail', {  
    'client_id': 'YOUR_CLIENT_ID',  
    'client_secret': 'YOUR_CLIENT_SECRET'  
})

Example: OAuth Flow Authentication for Salesforce​

Authenticate Salesforce connector using OAuth:

user.authenticate_connector('Salesforce', {  
    'access_token': 'USER_ACCESS_TOKEN',  
    'refresh_token': 'USER_REFRESH_TOKEN'  
})

Authentication Callbacks​

Instead of manually passing credentials every time, you can set an authentication callback. The callback function will dynamically supply the required credentials when the connector is being authenticated.

Example: Setting an Authentication Callback​

Define an authentication callback for multiple services:

def auth_callback(connector_name):  
    if connector_name == 'Gmail':  
        return {  
            'client_id': 'YOUR_CLIENT_ID',  
            'client_secret': 'YOUR_CLIENT_SECRET'  
        }  
    elif connector_name == 'Salesforce':  
        return {  
            'access_token': 'USER_ACCESS_TOKEN',  
            'refresh_token': 'USER_REFRESH_TOKEN'  
        }  
    else:  
        return None

Set the callback for user authentication:

user.set_auth_callback(auth_callback)

Now, whenever the user tries to authenticate a connector, the appropriate credentials will be fetched using the callback.

Handling Authentication Errors​

If authentication fails (e.g., invalid credentials or expired tokens), the Fiscus SDK raises an FiscusAuthenticationError. You can catch this exception and prompt the user to re-authenticate or handle it programmatically.

Example: Handling Authentication Failure​

from fiscus.exceptions import FiscusAuthenticationError

try:  
    user.authenticate_connector('Gmail')  
except FiscusAuthenticationError as e:  
    print(f"Authentication failed: {e}")  
    # Trigger a re-authentication flow

 

Listing Connected Connectors​

To manage connectors effectively, it’s often useful to list all connectors currently associated with a user. This allows you to audit the services each user is connected to and take action based on their needs.

Example: Listing All Connectors for a User​

List all connected connectors for the user:

connected_services = user.list_connected_connectors()  
print("User is connected to:", connected_services)

Example Use Case: Auditing Connectors for a User​

In enterprise environments, you may need to audit the connectors used by different teams or users. This ensures compliance with security protocols and helps in resource management.

Audit connected services:

for connector in user.list_connected_connectors():  
    print(f"User has access to: {connector}")

 

Conclusion​

Connector management in the Fiscus SDK allows for highly customizable, secure, and efficient API integrations at the user level. By dynamically adding, removing, and authenticating connectors, you can ensure that each user has the access they need without compromising security or performance. The SDK’s flexibility with callbacks and error handling ensures smooth user experiences while giving developers the tools they need to manage complex API ecosystems in their applications.