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_KEYenvironment 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.jsonto your.gitignoreand useappsettings.Development.jsonfor 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");
- 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.
- Local signed license: A successful activation stores
%APPDATA%\Eriksson Software\Eriksson Beam\ApiLicenseFile.lfxunder the Windows user running Beam. The desktop license uses a separate file. - 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
Pullalone cannot create it. - 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.