Set Role

Updates the AuthLevel (permission role) for a specified user, optionally scoping the role to a specific network or mailbox.

caution

Elevating a user's AuthLevel grants them additional access to networks, mailboxes, and ECGrid IDs. The Root and TechOps roles provide the broadest system access and should be assigned only to fully trusted administrators. Confirm the correct User ID and intended role before calling this endpoint.

Endpoint

POST /v2/users/role

Request Body

Field	Type	Required	Constraints	Description
userId	integer	Yes	Must be an existing user	ID of the user whose role to change
authLevel	AuthLevel	Yes	—	The new permission level to assign
networkId	integer	No	—	Scope the role to this network
mailboxId	integer	No	—	Scope the role to this mailbox

{
  "userId": 1042,
  "authLevel": "NetworkAdmin",
  "networkId": 1
}

Response

Returns the updated UserIDInfo object reflecting the new role.

{
  "success": true,
  "data": {
    "userId": 1042,
    "login": "jsmith",
    "email": "jsmith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "networkId": 1,
    "mailboxId": 101,
    "authLevel": "NetworkAdmin",
    "status": "Active",
    "created": "2024-03-15T10:22:00Z"
  }
}

ENUMs

This endpoint uses the following ENUM in its request body. See Appendix: ENUMs for full value lists.

• AuthLevel — the permission level to assign, from highest to lowest: Root, TechOps, NetOps, NetworkAdmin, NetworkUser, MailboxAdmin, MailboxUser, TPUser, General

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/users/role" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1042, "authLevel": "NetworkAdmin", "networkId": 1 }'

C#

// .NET 10 — Change a user's permission role using IHttpClientFactory
// Use sparingly for Root and TechOps — these roles have broad system access
public async Task<UserIdInfo?> SetRoleAsync(
    IHttpClientFactory httpClientFactory,
    int userId,
    string authLevel,
    int? networkId = null,
    int? mailboxId = null)
{
    var http = httpClientFactory.CreateClient("ECGridRest");

    var requestBody = new
    {
        userId,
        authLevel,
        networkId,
        mailboxId
    };

    var response = await http.PostAsJsonAsync(
        "https://rest.ecgrid.io/v2/users/role",
        requestBody);
    response.EnsureSuccessStatusCode();

    var result = await response.Content.ReadFromJsonAsync<ApiResponse<UserIdInfo>>();
    return result?.Data;
}

Java

import java.net.URI;
import java.net.http.*;

String apiKey = System.getenv("ECGRID_API_KEY");

String body = "{ \"userId\": 1042, \"authLevel\": \"NetworkAdmin\", \"networkId\": 1 }";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.ecgrid.io/v2/users/role"))
    .header("X-API-Key", apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Node.js

const apiKey = process.env.ECGRID_API_KEY;
const url = 'https://rest.ecgrid.io/v2/users/role';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "userId": 1042, "authLevel": "NetworkAdmin", "networkId": 1 }),
});

const data = await response.json();
console.log(data);

Python

import os, requests

api_key = os.environ["ECGRID_API_KEY"]
headers = {"X-API-Key": api_key}
url = "https://rest.ecgrid.io/v2/users/role"

response = requests.post(
    url,
    json={ "userId": 1042, "authLevel": "NetworkAdmin", "networkId": 1 },
    headers=headers,
)

response.raise_for_status()
print(response.json())

See Also

• Get User — confirm the user's current role before making changes
• List Users — filter users by AuthLevel to audit role assignments
• Update User — update other profile fields without changing the role