Skip to main content

Manage Users and Permissions

Create user accounts and assign the appropriate authorization level to control what each user can see and do within ECGrid.

Overview​

ECGrid uses a role-based permission model built around the AuthLevel enum. Each user account is assigned one level that determines which API operations and administrative functions they can perform. Levels range from General (read-only visibility) up through Root (full system access). In most integrations, application service accounts are assigned MailboxAdmin or NetworkAdmin depending on their scope.

Sequence:

  1. Create the user with POST /v2/users.
  2. Set the user's authorization level with POST /v2/users/role.
  3. Optionally list users with POST /v2/users/list to verify.

REST​

Auth: X-API-Key: <key> header

Step 1 — Create a user​

POST https://rest.ecgrid.io/v2/users
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "networkId": 0,
  "mailboxId": 54321,
  "loginName": "jsmith",
  "password": "S3cur3P@ssword!",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jsmith@example.com",
  "authLevel": "MailboxUser"
}
FieldTypeRequiredDescription
networkIdintegerNoNetwork to create the user under. Pass 0 for the API key's default network.
mailboxIdintegerNoMailbox to associate with this user. Pass 0 for network-level users.
loginNamestringYesUnique login name (no spaces).
passwordstringYesMust satisfy the complexity rule: uppercase, lowercase, digit, and special character.
firstNamestringYesUser's first name.
lastNamestringYesUser's last name.
emailstringYesEmail address for notifications and password resets.
authLevelstringNoInitial authorization level. Defaults to "General" if omitted.

Response:

{
  "success": true,
  "data": {
    "userId": 20100,
    "loginName": "jsmith",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jsmith@example.com",
    "authLevel": "MailboxUser",
    "status": "Active"
  }
}

Step 2 — Set the authorization level​

Use POST /v2/users/role to change a user's AuthLevel at any time, including at creation time if you want to set a different level than the default.

POST https://rest.ecgrid.io/v2/users/role
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "userId": 20100,
  "authLevel": "MailboxAdmin"
}
FieldTypeRequiredDescription
userIdintegerYesThe user ID returned from Step 1.
authLevelstringYesNew authorization level. See AuthLevel values below.

Response:

{
  "success": true,
  "data": {
    "userId": 20100,
    "authLevel": "MailboxAdmin"
  }
}

AuthLevel Values​

Levels are listed from highest privilege to lowest. A user can only perform actions at or below their assigned level.

AuthLevelScopeTypical Use
RootSystem-wideLoren Data internal — do not assign
TechOpsSystem-wideLoren Data internal — do not assign
NetOpsSystem-wideLoren Data operations — do not assign
NetworkAdminNetworkFull administrative access to a network and all its mailboxes
NetworkUserNetworkRead-only visibility across the network
MailboxAdminMailboxFull access to a specific mailbox and its trading partner relationships
MailboxUserMailboxStandard EDI send/receive access within a mailbox
TPUserTrading PartnerLimited access scoped to a specific ECGrid ID
GeneralNoneAuthenticated but no operational access — placeholder or pending setup

For complete definitions see Appendix: ENUMs — AuthLevel.

Step 3 — List users to verify​

POST https://rest.ecgrid.io/v2/users/list
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "networkId": 0,
  "mailboxId": 54321,
  "pageNo": 1,
  "recordsPerPage": 25
}

Confirm that the new user appears with the expected authLevel and status: "Active".

Code Examples​

// .NET 10 — create a user and assign a role using IHttpClientFactory (registered as "ECGrid")
// API key loaded from IConfiguration — never hardcoded
// Password loaded from IConfiguration — never hardcoded

using System.Net.Http.Json;

public record CreateUserRequest(
    int NetworkId,
    int MailboxId,
    string LoginName,
    string Password,
    string FirstName,
    string LastName,
    string Email,
    string AuthLevel);

public record SetRoleRequest(
    int UserId,
    string AuthLevel);

public record UserInfo(
    int UserId,
    string LoginName,
    string FirstName,
    string LastName,
    string Email,
    string AuthLevel,
    string Status);

public record ApiResponse<T>(bool Success, T Data);

public class ECGridUserService
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly IConfiguration _configuration;
    private readonly ILogger<ECGridUserService> _logger;

    public ECGridUserService(
        IHttpClientFactory httpClientFactory,
        IConfiguration configuration,
        ILogger<ECGridUserService> logger)
    {
        _httpClientFactory = httpClientFactory;
        _configuration    = configuration;
        _logger           = logger;
    }

    /// <summary>
    /// Creates a new ECGrid user and assigns the specified authorization level.
    /// </summary>
    /// <param name="loginName">Unique login name (no spaces).</param>
    /// <param name="firstName">User's first name.</param>
    /// <param name="lastName">User's last name.</param>
    /// <param name="email">Email address for the account.</param>
    /// <param name="authLevel">ECGrid AuthLevel to assign (e.g., "MailboxAdmin").</param>
    /// <param name="mailboxId">Mailbox to scope the user to. Pass 0 for network-level.</param>
    public async Task<UserInfo> CreateUserWithRoleAsync(
        string loginName,
        string firstName,
        string lastName,
        string email,
        string authLevel,
        int mailboxId = 0,
        CancellationToken cancellationToken = default)
    {
        var http = _httpClientFactory.CreateClient("ECGrid");

        // Load the initial password from configuration — do not hardcode
        string initialPassword = _configuration["ECGrid:NewUserPassword"]
            ?? throw new InvalidOperationException(
                "ECGrid:NewUserPassword is not configured. " +
                "Set it in appsettings or environment variables.");

        // Step 1 — create the user
        var createRequest = new CreateUserRequest(
            NetworkId:  0,
            MailboxId:  mailboxId,
            LoginName:  loginName,
            Password:   initialPassword,
            FirstName:  firstName,
            LastName:   lastName,
            Email:      email,
            AuthLevel:  "General");   // start at General, elevate below

        var createResponse = await http.PostAsJsonAsync(
            "/v2/users", createRequest, cancellationToken);
        createResponse.EnsureSuccessStatusCode();

        var createResult = await createResponse.Content
            .ReadFromJsonAsync<ApiResponse<UserInfo>>(cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("Empty response from user create.");

        _logger.LogInformation(
            "User created: ID={UserId} Login={Login}",
            createResult.Data.UserId, createResult.Data.LoginName);

        // Step 2 — elevate to the desired role
        var roleRequest = new SetRoleRequest(createResult.Data.UserId, authLevel);

        var roleResponse = await http.PostAsJsonAsync(
            "/v2/users/role", roleRequest, cancellationToken);
        roleResponse.EnsureSuccessStatusCode();

        _logger.LogInformation(
            "Role set: UserId={UserId} AuthLevel={AuthLevel}",
            createResult.Data.UserId, authLevel);

        // Return updated user info
        var verify = await http.GetFromJsonAsync<ApiResponse<UserInfo>>(
            $"/v2/users/{createResult.Data.UserId}", cancellationToken)
            ?? throw new InvalidOperationException("Could not retrieve user after role assignment.");

        return verify.Data;
    }
}

Registration in Program.cs:

builder.Services.AddHttpClient("ECGrid", client =>
{
    client.BaseAddress = new Uri("https://rest.ecgrid.io");
    client.DefaultRequestHeaders.Add(
        "X-API-Key",
        builder.Configuration["ECGrid:ApiKey"]);
});

builder.Services.AddScoped<ECGridUserService>();

:::caution Password Security Never hardcode passwords in source code or configuration files committed to source control. Load the initial password from environment variables or a secrets manager (e.g., Azure Key Vault, AWS Secrets Manager, .NET User Secrets for local development). :::

SOAP​

:::caution Established API The SOAP API is in maintenance mode. For new integrations use REST above. :::

Methods:

  • UserAdd(SessionID, NetworkID, MailboxID, LoginName, Password, ...) — create a user
  • UserSetAuthLevel(SessionID, UserID, AuthLevel) — assign the authorization level

Step 1 — Log in and get a session ID​

var loginResult = await client.LoginAsync(username, password);
string sessionId = loginResult.LoginResult;

Step 2 — Create the user with UserAdd​

var addResult = await client.UserAddAsync(
    sessionId,
    networkId:  0,
    mailboxId:  54321,
    loginName:  "jsmith",
    password:   Environment.GetEnvironmentVariable("NEW_USER_PASSWORD")!,
    firstName:  "Jane",
    lastName:   "Smith",
    email:      "jsmith@example.com");

int userId = addResult.UserAddResult.UserID;
Console.WriteLine($"User created: ID={userId}");

Step 3 — Assign the role with UserSetAuthLevel​

await client.UserSetAuthLevelAsync(
    sessionId,
    userId:    userId,
    authLevel: AuthLevel.MailboxAdmin);

Console.WriteLine($"AuthLevel set to MailboxAdmin for user {userId}");

Code Examples​

// .NET 10 — dotnet-svcutil generated proxy
// Reference: https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx?WSDL

using ECGridOS;

var binding  = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
var endpoint = new EndpointAddress("https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx");
var client   = new ECGridOSAPIClient(binding, endpoint);

string sessionId = string.Empty;

try
{
    var loginResult = await client.LoginAsync(
        Environment.GetEnvironmentVariable("ECGRID_USER")!,
        Environment.GetEnvironmentVariable("ECGRID_PASS")!);
    sessionId = loginResult.LoginResult;

    // Create the user
    var addResult = await client.UserAddAsync(
        sessionId,
        networkId:  0,
        mailboxId:  54321,
        loginName:  "jsmith",
        password:   Environment.GetEnvironmentVariable("NEW_USER_PASSWORD")!,
        firstName:  "Jane",
        lastName:   "Smith",
        email:      "jsmith@example.com");

    int userId = addResult.UserAddResult.UserID;
    Console.WriteLine($"User created: ID={userId}");

    // Assign the authorization level
    await client.UserSetAuthLevelAsync(
        sessionId,
        userId:    userId,
        authLevel: AuthLevel.MailboxAdmin);

    Console.WriteLine("AuthLevel assigned: MailboxAdmin");
}
finally
{
    if (!string.IsNullOrEmpty(sessionId))
        await client.LogoutAsync(sessionId);
}