User Identification

Exago does not have native user authentication. User logins must be handled in a security layer in the embedding application. After a user logs in, the application should pass identification parameters to the Exago API, which you can use to set permissions.

userId and companyId

Exago has two built-in parameters which are used to store identifying information: userId and companyId. These parameters are used in conjunction with the Schedule Manager and User Preferences, and they are automatically passed to any extensions which may need to access authentication. Folder Management, External Interface, Scheduler Queue, and any extension which can access sessionInfo (such as Assembly Data Sources or Server Events) can retrieve these parameters in relevant methods.

Note: These are required parameters. They cannot be deleted through the Admin Console, and if they are not present in the Config, then they are automatically added at load time.

Often userId corresponds with a unique user or log-in, and companyId represents a group of users with shared characteristics. Either parameter can be used without the other.

userEmail (v2018.2+)

The userEmail parameter is a third built-in parameter that can specify an email to be set as the "Reply To" email for any scheduled reports. If using the userId or companyId parameters to identify the user, it is possible to change the default value of userEmail to be specific to the users identified by userId or companyId. See below for an example of this in the .NET API and REST API. For more information about this parameter see Scheduler Reply To Address.

Setting the current user


The Id parameters are added by default in the base config file with blank values.


The Id parameters are not instantiated by default, and must be created before use. They can be created in the Admin Console, config file, or in the API code. They must be created with the exact names of "userId" and "companyId" (which are case sensitive), with data type "string". Since the values are set in the API, if you create the parameters in the Admin Console or config, they should have blank default values.

Admin Console

As created in the Admin Console:


Config File

As created in the config file:

<value />
<prompt_text />
<value />
<prompt_text />

The userEmail parameter (v2018.2+):

<value />
<prompt_text />


As created in the .NET API:

Note: "DataType" defaults to DataType.String, so the call is omitted.
Parameter userId = api.Parameters.NewParameter();
userId.Id = "userId";
userId.Value = "user_224";

Parameter companyId = api.Parameters.NewParameter();
companyId.Id = "companyId";
companyId.Value = "company_17";

For setting the userEmail parameter (v2018.2+):

Parameter userId = api.Parameters.GetParameterById("userEmail");
userId.Value = "";


As created in the REST API:

Note: "DataType" defaults to "String", so the call is omitted.

POST /parameters

"Id": "userId",
"Value": "user_224"

POST /parameters

"Id": "companyId",
"Value": "company_17"

For setting the userEmail parameter (v2018.2+):

POST /parameters

"Id": "userEmail",
"Value": ""


Basic sandboxing

Setting the userId and companyId parameters has several effects in the Exago interface.

Schedule Manager

By default, the Schedule Manager will show only schedules belonging to the current userId. This can be changed by modifying the following Admin Console setting:

Scheduler Manager User View Level (Scheduler Settings)

  • Current User ('User'): Filters schedules by current userId parameter.
  • All Users in Current Company ('Company'): Filters schedules by current companyId parameter.
  • All Users in All Companies ('All'): No filtering.

This setting can also be overridden by a Role.

Execution Cache

The userId and companyId parameters are used to set permissions for which users can view cached report data. Users can choose whether a report cache is visible just for their userId, for everyone with the same companyId, or for all users. The options that are available to a user depends on the following setting:

User Cache Visibility Level (Scheduler Settings)

User Preferences

User preferences, including which reports should run on startup and User Reports (live report customization), are set by userId, and will only apply to that user.

Advanced permissions

userId and companyId can be used in many other application areas in order to handle security permissions.


Additional permissions are typically handled by Roles. A check can be made in the API which maps the current userId and/or companyId to the role which it belongs. This must be handled manually via a lookup table or a similar data structure. Then activate the role for the session.

.NET: api.Roles.GetRole("admin").Activate();

REST: PATCH /REST/Roles/admin?sid={sid} { "IsActive": true }

For more information, see Roles.


userId and companyId can be used as tenant parameters in your data objects.

If your data is set up such that each table, view and stored procedure has columns that indicate which user has access to each row, then you can use userId and/or companyId to match these columns and act as data row filters. (For this purpose, the parameters cannot be set to 'hidden').

For more information, see Multi-Tenant Environment Integration.

Accessing Ids in extensions

userId and companyId are passed to any custom extensions where relevant. For example, in an external interface assembly, you may wish to access the userId in order to log user executions. You could do so by implementing the ReportExecuteStart method, which passes the userId parameter.

public static void ReportExecuteStart(string companyId, string userId, string reportName)
string logText = string.Format("{0}: Report '{1}' executed by user '{2}'.", DateTime.Now, reportName, userId);

File.AppendAllText(logFile, logText + Environment.NewLine);

This would return the following text upon a report execution by userId "Alex":

2017-03-07 14:50:49: Report 'Test\Product Sales Report' executed by user 'Alex'.

Most extensions have methods which can access userId and companyId. In addition, the parameters are accessible through sessionInfo. So any extensions which can access sessionInfo can also access userId and companyId, even if methods do not explicitly implement them.

The following server event automatically adds the userId to the description text whenever a report is saved.

Global Event Type: OnReportSaveStart, References: WebReports.Api.Reports

Report report = sessionInfo.Report;
string userId = sessionInfo.UserId;
if (!report.Description.EndsWith(userId)) { report.Description += ("\n" + userId); }
return null;

Hidden Article Information

Article Author
Exago Development
created 2017-03-01 18:48:06 UTC
updated 2019-07-09 20:36:31 UTC

parameters, permissions, userId, companyId, user preferences, schedule manager,
Have more questions? Submit a request