Skip to main content

User Authentication and Tokens

Fiscus provides a flexible and comprehensive authentication system to manage OAuth flows, API keys, and token management across different APIs and services. Through the Fiscus SDK, you can handle multiple authentication methods seamlessly, allowing users to interact with APIs without needing to manage complex auth processes manually.

Overview of Authentication in Fiscus​

Fiscus supports various authentication methods, including:

  • OAuth 2.0: Handles user consent flows and access token management for services that require OAuth (e.g., Google, Salesforce).
  • API Keys: Supports APIs that use static API keys for authentication.
  • Token Management: Fiscus abstracts away the complexity of token refresh and expiration, ensuring that tokens are always valid during API interactions.
  • Custom Authentication: Developers can define their own custom authentication logic and use Fiscus to manage these custom flows.

The SDK simplifies authentication for developers by providing a unified interface for multiple services, making it easy to integrate and manage API authentication.

OAuth 2.0 Authentication​

OAuth 2.0 is a common authentication method used by many modern APIs (e.g., Google, Microsoft, Facebook). It involves obtaining an access token after the user grants permission, and Fiscus handles this flow natively.

Example: OAuth Flow for Gmail​

In this example, we’ll see how to authenticate a user with Gmail using OAuth and how Fiscus manages the token for you.

from fiscus import FiscusClient, FiscusUser

Initialize Fiscus client and user

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

# OAuth authentication for Gmail
user.authenticate_connector('Gmail', auth_params={
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET',
    'redirect_uri': 'YOUR_REDIRECT_URI',
    'code': 'AUTHORIZATION_CODE_RECEIVED_FROM_GMAIL'
})

How OAuth Works in Fiscus:​

  1. Client ID and Secret: These are provided by the API service (e.g., Google) when you register your application.
  2. Authorization Code: The user is redirected to the OAuth provider to grant permission. After consent, you receive an authorization code.
  3. Token Management: Fiscus handles the exchange of this authorization code for an access token and manages refreshing the token as needed.

Token Refresh:​

Fiscus automatically refreshes OAuth tokens before they expire, so the developer doesn’t have to manage this process manually. You can override this behavior by providing your custom token refresh logic.

Custom Token Refresh Example​

If you want to customize how tokens are refreshed:

def custom_refresh_token_callback(connector_name):
    # Custom logic to refresh the token
    if connector_name == 'Gmail':
        return {
            'access_token': 'NEW_ACCESS_TOKEN',
            'refresh_token': 'NEW_REFRESH_TOKEN'
        }

Set the custom callback

user.set_auth_callback(custom_refresh_token_callback)

OAuth Scopes​

You can specify which scopes to request during the authentication process:

user.authenticate_connector('Gmail', auth_params={
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET',
    'redirect_uri': 'YOUR_REDIRECT_URI',
    'code': 'AUTHORIZATION_CODE',
    'scopes': ['https://mail.google.com/', 'https://www.googleapis.com/auth/userinfo.email']
})

 

API Key Authentication​

Some APIs use static API keys for authentication. Fiscus allows you to store and manage these keys securely, abstracting away the need to embed them in your code.

Example: Authenticating with an API Key​

from fiscus import FiscusUser, FiscusClient

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

# Authenticate with API Key for a service
user.authenticate_connector('Stripe', auth_params={
    'api_key': 'YOUR_STRIPE_API_KEY'
})

How Fiscus Handles API Keys:​

  1. Secure Storage: API keys are stored securely within the Fiscus SDK, reducing the risk of exposing sensitive credentials.
  2. Automatic Use: Once authenticated, Fiscus uses the API key for all subsequent requests to that service, ensuring smooth, continuous access.

Token Management​

Tokens, whether OAuth access tokens or custom tokens, are critical for maintaining access to authenticated services. Fiscus provides comprehensive token management, including automatic refresh, expiration handling, and secure storage.

Automatic Token Refresh​

For services that use OAuth or other token-based authentication methods, Fiscus automatically refreshes the token before it expires. You can override this by providing your own token management logic.

Example: Custom Token Management​

If you want full control over token handling, you can define custom logic for both setting and refreshing tokens.

def custom_auth_callback(connector_name):
    if connector_name == 'CustomAPI':
        return {
            'access_token': 'CUSTOM_ACCESS_TOKEN',
            'refresh_token': 'CUSTOM_REFRESH_TOKEN'
        }

# Set custom authentication callback
user.set_auth_callback(custom_auth_callback)

# Authenticate using the custom tokens
user.authenticate_connector('CustomAPI')

Managing Token Expiry​

Fiscus keeps track of token expiry times, ensuring tokens are refreshed before they expire. This eliminates the need for developers to monitor token lifetimes manually.

Example: Handling Expired Tokens​

from fiscus.exceptions import FiscusAuthenticationError

try:
    response = client.execute('Gmail', 'send_email', email_params, user=user)
except FiscusAuthenticationError:
    # Token might be expired; handle re-authentication
    user.authenticate_connector('Gmail')
    response = client.execute('Gmail', 'send_email', email_params, user=user)

Custom Token Storage​

If you need to store tokens in your own infrastructure, Fiscus allows you to provide custom storage and retrieval mechanisms.

Example: Custom Token Storage​

def custom_token_loader(connector_name):
    # Load token from custom storage
    return load_token_from_db(connector_name)

def custom_token_saver(connector_name, token_data):
    # Save token to custom storage
    save_token_to_db(connector_name, token_data)

# Set custom token loader and saver
client.set_token_loader(custom_token_loader)
client.set_token_saver(custom_token_saver)

 

Other Authentication Methods​

Basic Authentication​

Some APIs use Basic Authentication, where a username and password are used. Fiscus also supports this method.

user.authenticate_connector('BasicAPI', auth_params={
    'username': 'your_username',
    'password': 'your_password'
})

Bearer Token Authentication​

For APIs that require Bearer tokens, you can authenticate by providing the token directly.

user.authenticate_connector('BearerAPI', auth_params={
    'access_token': 'YOUR_BEARER_TOKEN'
})

 

Custom Authentication Flows​

If you are integrating with a custom API or a service with non-standard authentication, Fiscus allows you to define your own authentication flows. You can use the auth_callback to implement custom logic based on the connector.

Example: Custom Auth Flow​

def custom_auth_flow(connector_name):
    if connector_name == 'MyCustomAPI':
        # Implement custom logic to retrieve or refresh token
        return {
            'access_token': 'CUSTOM_ACCESS_TOKEN'
        }

user.set_auth_callback(custom_auth_flow)
user.authenticate_connector('MyCustomAPI')

Token Revocation​

You can also revoke tokens when necessary (e.g., during logout or account deactivation).

Example: Revoking a Token​

user.deauthenticate_connector('Gmail')

This ensures that the token is no longer valid, and the user must re-authenticate.

 

Wrapping Up User Authentication and Tokens​

  • Simplified Authentication: Fiscus handles complex OAuth flows, API keys, and token management, abstracting it all into easy-to-use methods.
  • Token Refresh and Rotation: Automatic handling of token refreshes ensures your integrations remain uninterrupted and secure.
  • Customizable Authentication: Support for custom authentication flows, including callbacks, lets you easily adjust to different API standards.
  • Unified Framework: Manage authentication across multiple APIs and services through a single, unified framework without manual credential handling.
  • Security Focused: Fiscus abstracts and simplifies authentication, while ensuring secure storage and usage of sensitive credentials.
  • Scalability: Fiscus’s architecture scales easily with your application, supporting growing user bases and expanding API connections without added complexity.

In summary, Fiscus provides an all-encompassing solution for managing user authentication and token security. Whether you're integrating with OAuth-based APIs, handling API keys, or navigating token refreshes, the Fiscus SDK simplifies and automates the process. With its flexible, customizable authentication flow options, you can manage secure connections at scale, without getting bogged down by manual implementations. This ensures that your AI-powered applications remain connected, secure, and compliant, even as they grow in complexity.