SuperOffice DevNet Python System User

This project demonstrates how to obtain a SuperOffice system user ticket from a system user token using Python. The system user ticket is a credential type that can be used when calling SuperOffice web services for server-to-server authentication.

Purpose

The SystemUserTokenRest class exchanges a system user token for a system user ticket, which is one of the accepted credential types when calling SuperOffice web services. This is useful for:

• Server-to-server integrations with SuperOffice
• Automated processes that need to authenticate with SuperOffice APIs
• Applications that require secure access to SuperOffice data without user interaction

Prerequisites

• Python 3.13 or higher
• A SuperOffice application token (client secret)
• A private key file (.xml or .pem format)
• A valid system user token from SuperOffice
• Customer context identifier (e.g., Cust12345)

Installation Options

Option 1: Using uv (Recommended)

uv is a fast Python package installer and resolver written in Rust. It provides better performance and dependency resolution than pip.

Install uv

Windows:

# Using PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

# Using curl
curl -LsSf https://astral.sh/uv/install.sh | sh

Alternative installation methods:

• Download from GitHub releases
• Using pip: pip install uv
• Using conda: conda install -c conda-forge uv

Setup with uv

1. Clone or download this repository

2. Navigate to the project directory:

   cd devnet-python-system-user

3. Create a virtual environment and install dependencies:

   uv sync

4. Activate the virtual environment:

   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate

Option 2: Using pip and venv

If you prefer to use the standard Python tools:

1. Clone or download this repository

2. Navigate to the project directory:

   cd devnet-python-system-user

3. Create a virtual environment:

   python -m venv .venv

4. Activate the virtual environment:

   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate

5. Install dependencies:

   pip install -r requirements.txt

   Note: If you encounter issues with suds-jurko on Python 3.13+, install alternative packages:

   pip install suds-py3 pyOpenSSL pycryptodome pyJWT requests

Configuration

1. Update your private key file

Ensure you have either:

• private.xml (RSA XML format)
• private.pem (PEM format)

Place this file in the project root directory.

2. Update main.py

Edit the main.py file and update the following settings:

# Option 1: Using REST-based implementation (recommended)
from SystemUserTokenRest import SystemUserTokenRest

# create instance of SystemUserTokenRest
#   application_token: your application secret from SuperOffice
#   private_key_file:  'private.xml' or 'private.pem'
#   environment:       'sod' | 'stage' | 'online'

systemuser = SystemUserTokenRest(
    'your_application_token_here',    # Replace with your app token
    'private.xml',                    # Replace with your key file
    'sod'                             # Replace with your environment
)

# get the system user ticket and webapi url
#   system_user_token:  token received after admin successful interactive login
#   context_identifier: customer id, e.g. 'Cust12345'

result = systemuser.get_system_user_ticket(
    'your_system_user_token_here',   # Replace with your system user token
    'Cust12345'                      # Replace with your customer ID
)

# Check if authentication was successful
if result.is_success:
    print(f'System user ticket: {result.ticket}')
    print(f'WebAPI URL: {result.webapi_url}')
else:
    print(f'Authentication failed: {result.error_message}')

# Option 2: Using SOAP-based implementation (legacy)
from SystemUserToken import SystemUserToken

systemuser = SystemUserToken(
    'your_application_token_here',    # Replace with your app token
    'private.xml',                    # Replace with your key file
    'sod'                            # Replace with your environment
)

ticket = systemuser.get_system_user_ticket(
    'your_system_user_token_here',   # Replace with your system user token
    'Cust12345'                      # Replace with your customer ID
)

print('System user ticket: ' + ticket)

Configuration Parameters

• application_token: Your SuperOffice application secret/client secret (from your app registration https://dev.superoffice.com)
• private_key_file: Path to your private key file (private.xml or private.pem) (from your app configuration - the certificate you generated in the app configuration on the DevNet portal)
• environment: Target environment
  • 'sod' - SuperOffice Development environment
  • 'stage' - Staging environment
  • 'online' - Production environment
• system_user_token: The token received after successful admin interactive login
• context_identifier: Your customer identifier (format: CustXXXXX)

Return Types

REST Implementation (SystemUserTokenRest)

The REST implementation returns a SystemUserResult dataclass with the following fields:

• ticket (str): The system user ticket for authentication
• webapi_url (str): The WebAPI URL for the tenant
• is_success (bool): Whether the authentication was successful
• error_message (str): Error details if authentication failed

result = systemuser.get_system_user_info(token, context_id)

if result.is_success:
    # Use result.ticket for authentication
    # Use result.webapi_url for API calls
    api_call_url = f"{result.webapi_url}v1/Contact"
else:
    print(f"Error: {result.error_message}")

SOAP Implementation (SystemUserToken)

The SOAP implementation returns a simple string containing the system user ticket, or 'Failed!' on error.

Running the Script

1. Ensure your virtual environment is activated

2. Run the script:

   python main.py

3. If successful, you should see output similar to:

   REST Implementation:

   System user ticket: 7T:ABCjADsDfDAxAGEAZgA2ADQAZAA2ADgANQAwAGQAOQBjADEANABkAGIAMgBmADgAZgAxAGQAMwA1ADQANQA2ADsAMQA3ADgANQAyADEAMAA2ADEAMUE7AEMAdQBzAHQAMgA2ADcSAMP7ES==
   WebAPI URL: https://sod.superoffice.com/Cust12345/api/
   

   SOAP Implementation:

   System user ticket: 7T:NABjADgAMgAxAGEAZgA2ADQAZAA2ADgANQAwAGQAOQBjADEANABkAGIAMgBmADgAZgAxAGQAMwA1ADQANQA2ADsAMQA3ADgANQAyADEAMAA2ADEAMUE7AEMAdQBzAHQAMgA2ADcANQA5AA==
   

Troubleshooting

Common Issues

1. Import errors: Ensure all dependencies are installed in your virtual environment
2. SSL/TLS errors: Verify your private key file is correctly formatted
3. Authentication errors: Check that your application token and system user token are valid
4. Environment errors: Ensure you're using the correct environment setting

Dependency Issues

If you encounter issues with suds-jurko on newer Python versions:

# Uninstall problematic package
pip uninstall suds-jurko

# Install compatible alternatives
pip install suds-py3 pyJWT

Python Version Compatibility

This project is tested with Python 3.13+. For older Python versions, you may need to adjust dependencies in requirements.txt.

Files in this Project

• main.py - Main script demonstrating the REST-based system user token exchange
• SystemUserTokenRest.py - REST-based implementation with enhanced return type (recommended)
• SystemUserToken.py - Original SOAP-based implementation (legacy)
• requirements.txt - Python dependencies for pip
• pyproject.toml - Project configuration and dependencies for uv
• private.xml / private.pem - Your private key files (not included)
• PartnerSystemUserService.wsdl - WSDL file for SOAP operations

Why Use the REST Implementation?

The REST-based implementation (SystemUserTokenRest) is recommended over the SOAP implementation for the following reasons:

Enhanced Return Type

• Returns a structured SystemUserResult object instead of a simple string
• Provides both the system user ticket AND the WebAPI URL
• Includes success status and detailed error messages
• Better error handling and debugging capabilities

Modern Dependencies

• Uses the cryptography library instead of the deprecated OpenSSL crypto functions
• More compatible with modern Python versions (3.8+)
• Better security and performance

Example Benefits

# REST implementation provides more information
result = systemuser.get_system_user_info(token, context_id)

if result.is_success:
    # You get both pieces of information you need
    ticket = result.ticket           # For authentication
    api_base = result.webapi_url     # For making API calls
    
    # Make an API call
    api_url = f"{api_base}v1/Contact"
    headers = {
        "Authorization": f"SOTicket {ticket}",
        "SO-Token": "{client_secret}"
        }
else:
    # Clear error information
    print(f"Authentication failed: {result.error_message}")

Security Notes

• Keep your private key files secure and never commit them to version control
• Store application tokens and system user tokens securely
• Use environment variables for sensitive configuration in production

Support

For more information about SuperOffice system user authentication, visit the SuperOffice Developer Network.