Session

Retrieve information about the currently authenticated session, including the user identity, network and mailbox context, and token expiry.

Endpoint

POST /v2/auth/session

Request Body

No request body is required. Session details are resolved from the Authorization or X-API-Key header.

Response

Returns the session context for the currently authenticated principal.

{
  "success": true,
  "data": {
    "userId": 4821,
    "login": "jsmith@example.com",
    "networkId": 1,
    "mailboxId": 101,
    "authLevel": "MailboxAdmin",
    "expiresAt": "2026-05-07T18:30:00Z"
  },
  "errorCode": "",
  "message": ""
}

Field	Type	Description
userId	integer	Internal ECGrid user ID
login	string	Username / login identifier
networkId	integer	ECGrid network ID the user belongs to
mailboxId	integer	Primary mailbox ID associated with the session
authLevel	string	Current authorization level — see AuthLevel ENUM below
expiresAt	datetime (ISO 8601)	UTC expiry time of the current token or session

ENUMs

AuthLevel

Value	Description
NoChange	No change to current level
Root	System root access
TechOps	Technical operations
NetOps	Network operations
NetworkAdmin	Full network administration
NetworkUser	Standard network user
MailboxAdmin	Full mailbox administration
MailboxUser	Standard mailbox user
TPUser	Trading partner user
General	General read-only access

See Appendix — ENUMs for the full AuthLevel reference.

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/auth/session" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "success": true, "data": { "userId": 4821, "login": "jsmith@example.com", "networkId": 1, "mailboxId": 101, "authLevel": "MailboxAdmin", "expiresAt": "2026-05-07T18:30:00Z" }, "errorCode": "", "message": "" }'

C#

// .NET 10 — Retrieve and inspect the current session
using System.Net.Http.Json;

/// <summary>
/// Fetches the current session details to verify authentication and check the auth level.
/// </summary>
async Task<SessionData?> GetSessionAsync(HttpClient httpClient)
{
    var response = await httpClient.PostAsync(
        "https://rest.ecgrid.io/v2/auth/session",
        content: null);

    response.EnsureSuccessStatusCode();

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

record SessionData(
    int UserId,
    string Login,
    int NetworkId,
    int MailboxId,
    string AuthLevel,
    DateTime ExpiresAt);

record ApiResponse<T>(bool Success, T? Data, string ErrorCode, string Message);

Java

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

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

String body = "{ \"success\": true, \"data\": { \"userId\": 4821, \"login\": \"jsmith@example.com\", \"networkId\": 1, \"mailboxId\": 101, \"authLevel\": \"MailboxAdmin\", \"expiresAt\": \"2026-05-07T18:30:00Z\" }, \"errorCode\": \"\", \"message\": \"\" }";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.ecgrid.io/v2/auth/session"))
    .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/auth/session';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "success": true, "data": { "userId": 4821, "login": "jsmith@example.com", "networkId": 1, "mailboxId": 101, "authLevel": "MailboxAdmin", "expiresAt": "2026-05-07T18:30:00Z" }, "errorCode": "", "message": "" }),
});

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/auth/session"

response = requests.post(
    url,
    json={ "success": true, "data": { "userId": 4821, "login": "jsmith@example.com", "networkId": 1, "mailboxId": 101, "authLevel": "MailboxAdmin", "expiresAt": "2026-05-07T18:30:00Z" }, "errorCode": "", "message": "" },
    headers=headers,
)

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

See Also

• Login — obtain a session token
• Refresh Token — extend the session before expiresAt
• Logout — terminate the current session
• Appendix — ENUMs