List Keys

Returns all API keys associated with a user, optionally filtered by visibility level.

Endpoint

POST /v2/keys/list

Request Body

Field	Type	Required	Constraints	Description
userId	int	Yes	Must be a valid user ID	The ID of the user whose keys should be listed
visibility	string	No	Must be a valid KeyVisibility value	Filter results to keys with this visibility level

{
  "userId": 12345,
  "visibility": "Private"
}

Response

Returns an array of key records matching the specified criteria.

{
  "success": true,
  "data": [
    {
      "keyId": 9001,
      "userId": 12345,
      "key": "ek_live_abc123xyz789...",
      "visibility": "Private",
      "created": "2025-01-15T10:30:00Z"
    },
    {
      "keyId": 9002,
      "userId": 12345,
      "key": "ek_shared_def456uvw...",
      "visibility": "Shared",
      "created": "2025-03-20T14:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
keyId	int	Unique identifier for this key record
userId	int	The user this key belongs to
key	string	The API key string used for authentication
visibility	string	Scope of the key — see KeyVisibility enum
created	datetime	UTC timestamp when the key was created

ENUMs

KeyVisibility

See KeyVisibility in the Appendix for the full list of values.

Value	Description
Private	Key is accessible only to the owning user
Shared	Key is shared within the mailbox or network
Public	Key is publicly accessible
Session	Key is tied to a single session

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/keys/list" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 12345, "visibility": "Private" }'

C#

// .NET 10 — List all API keys for a user, filtered to Private visibility
using System.Net.Http.Json;

var request = new
{
    userId = 12345,
    visibility = "Private"
};

var response = await httpClient.PostAsJsonAsync(
    "https://rest.ecgrid.io/v2/keys/list",
    request);

response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<ApiResponse<List<KeyInfo>>>();

foreach (var key in result?.Data ?? [])
{
    Console.WriteLine($"KeyId: {key.KeyId} | Visibility: {key.Visibility} | Created: {key.Created:d}");
}

Java

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

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

String body = "{ \"userId\": 12345, \"visibility\": \"Private\" }";

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

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

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/keys/list"

response = requests.post(
    url,
    json={ "userId": 12345, "visibility": "Private" },
    headers=headers,
)

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

See Also

• Get Key
• Create Key
• Delete Key
• KeyVisibility Enum