Eriksson Beam API
Search Results for

    Show / Hide Table of Contents

    License Setup

    The Eriksson Beam API requires a valid API license key for all operations. This guide covers how to obtain, configure, and manage your API license key.

    Understanding Licensing

    Eriksson Beam has two separate licenses:

    License Purpose How to Obtain
    Desktop License Run the Eriksson Beam application Included with purchase/subscription
    API License Key Use the automation API Contact support@erikssonsoftware.com

    This guide covers the API License Key configuration. Your desktop license is handled separately during software installation and activation.

    Note: The API license key is a separate credential from your desktop application license. Because it is distinct, the samples and this guide reference it through the BEAM_API_LICENSE_KEY environment variable to avoid confusion with the desktop license.

    Obtaining an API License Key

    Contact Eriksson Software to obtain an API license key:

    • Email: support@erikssonsoftware.com
    • Website: Contact form on the Eriksson Software website

    Your API license consists of a numeric license ID and an activation password. You combine them into a single key string in the form licenseId:activationPassword:

    12345:your-activation-password
    

    The license ID is the number before the first colon; everything after the first colon is the activation password (the password itself may contain colons).

    Configuring Your API License Key

    Recommended: Environment Variable

    Store your API license key in an environment variable for security:

    Windows (Command Prompt):

    setx BEAM_API_LICENSE_KEY "12345:your-activation-password"
    

    Windows (PowerShell):

    [Environment]::SetEnvironmentVariable("BEAM_API_LICENSE_KEY", "12345:your-activation-password", "User")
    

    In your code:

    var licenseKey = Environment.GetEnvironmentVariable("BEAM_API_LICENSE_KEY");
    
    var launcherArgs = new ErikssonBeamLauncherArgs
    {
        LicenseKey = licenseKey,
        // ...
    };
    

    Alternative: Configuration File

    For applications with configuration files, use appsettings.json:

    {
      "ErikssonBeam": {
        "LicenseKey": "YOUR-LICENSE-KEY-HERE"
      }
    }
    

    Load in code:

    var configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .Build();
    
    var licenseKey = configuration["ErikssonBeam:LicenseKey"];
    

    Security Warning: Never commit license keys to source control. Add appsettings.json to your .gitignore and use appsettings.Development.json for local development.

    Not Recommended: Hardcoded

    Avoid hardcoding license keys in source code:

    // DON'T do this - key will be in source control and compiled binary
    var launcherArgs = new ErikssonBeamLauncherArgs
    {
        LicenseKey = "12345:your-activation-password",  // Bad practice!
        // ...
    };
    

    How License Validation Works

    Connecting opens the pipe; it does not validate or activate the API license. Before the first data operation, authenticate explicitly:

    await client.AuthenticateAsync();
    var design = await client.PullBeamDesignerAsync("DefaultSeedBeam");
    

    AuthenticateAsync() uses the key supplied in the connection or launcher arguments and throws ServerErrorException if authentication fails.

    If authentication itself hangs after Beam receives the request, see Authentication Request Times Out. Affected Beam v6 desktop builds require the asynchronous authentication fix; an SDK update alone cannot fix the server handler.

    For SDK versions without this helper, send the existing protocol request directly:

    using ErikssonBeam.API.BeamClient;
    using ErikssonBeam.API.Pipes.Messaging.Requests;
    using ErikssonBeam.API.Pipes.Messaging.Responses;
    
    var authentication = await client.SubmitRequest<AuthenticateResponse>(
        new AuthenticateRequest(licenseKey));
    if (authentication.ResponseCode != ResponseCode.Success)
        throw new ServerErrorException(authentication);
    
    var design = await client.PullBeamDesignerAsync("DefaultSeedBeam");
    
    1. First activation: Authentication checks for a valid local API license for the supplied ID. If none exists, it attempts online activation, which consumes one available activation.
    2. Local signed license: A successful activation stores %APPDATA%\Eriksson Software\Eriksson Beam\ApiLicenseFile.lfx under the Windows user running Beam. The desktop license uses a separate file.
    3. Subsequent use: Authentication reuses a valid local API license without activating again. High-level data methods validate that local license using the configured key; connecting and calling Pull alone cannot create it.
    4. Session tokens: Authentication also returns a token for callers constructing protocol requests themselves. The high-level data methods continue using the configured key.

    A LicenseError on the first Pull can therefore mean authentication was omitted, even when the product and key are correct and activations remain. If explicit authentication also fails, check the activation password, API product, network access, and local license status.

    License Errors

    Common Error Codes

    Error Meaning Resolution
    LicenseError No valid local API license, rejected authentication, or insufficient tier Authenticate first; then check credentials and permissions

    Handling License Errors

    try
    {
        var design = await client.PullBeamDesignerAsync();
    }
    catch (ServerErrorException ex) when (ex.Response.ResponseCode == ResponseCode.LicenseError)
    {
        Console.WriteLine("License validation failed. Please check your license key.");
        Console.WriteLine($"Details: {ex.Response.ErrorMessage}");
    }
    

    Testing Your Setup

    Verify your license is working with this test program:

    using System;
    using System.Threading.Tasks;
    using ErikssonBeam.API.BeamClient;
    
    class LicenseTest
    {
        static async Task Main()
        {
            var licenseKey = Environment.GetEnvironmentVariable("BEAM_API_LICENSE_KEY");
    
            if (string.IsNullOrEmpty(licenseKey))
            {
                Console.WriteLine("ERROR: BEAM_API_LICENSE_KEY environment variable not set");
                return;
            }
    
            Console.WriteLine("License key found. Attempting connection...");
    
            var args = new ErikssonBeamConnectionAttemptArgs
            {
                LicenseKey = licenseKey,
                MaxAttempts = 3,
                WaitTimeBetweenAttemptsMs = 1000
            };
    
            try
            {
                // This requires Eriksson Beam to be running
                using var client = await ErikssonBeamFinder.GetFirstSupportedBeamClient(args);
                await client.AuthenticateAsync();
                Console.WriteLine("SUCCESS: Connected to Eriksson Beam!");
                Console.WriteLine("License key is valid.");
            }
            catch (ErikssonBeamNotRunningException)
            {
                Console.WriteLine("Eriksson Beam is not running.");
                Console.WriteLine("Start Eriksson Beam and try again to verify your license.");
            }
            catch (ServerErrorException ex)
            {
                Console.WriteLine($"License error: {ex.Response.ErrorMessage}");
            }
        }
    }
    

    Multiple Environments

    For different environments (development, staging, production), use separate environment variables or configuration files:

    #if DEBUG
        var licenseKey = Environment.GetEnvironmentVariable("BEAM_API_LICENSE_KEY_DEV");
    #else
        var licenseKey = Environment.GetEnvironmentVariable("BEAM_API_LICENSE_KEY_PROD");
    #endif
    

    API License Key Security Checklist

    • [ ] Store API license key in environment variable or secure configuration
    • [ ] Never commit API license keys to source control
    • [ ] Add configuration files with keys to .gitignore
    • [ ] Use different keys for development and production if available
    • [ ] Rotate keys if they may have been exposed

    Next Steps

    With your license configured, proceed to First Connection to start using the API.

    • Edit this page
    In this article
    Back to top Generated by DocFX