Users

User lookup by id, email, or me.

Namespace: Goodmem.Client.Api · Class: UsersApi

Reach this surface as client.Users on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

CreateAsync

Creates one dormant human user after requiring instance-wide CREATE_USER authority. Creation does not issue a credential or create a role, grant, or authentication mapping.

Declaration

public Task<UserResponse> CreateAsync(CreateUserRequest request, CancellationToken ct = default)

HTTP — POST /v1/users

Parameters

Returns

Task<UserResponse> — an awaitable that resolves to UserResponse.

Exceptions

Example

var createdUser = await client.Users.CreateAsync(
    new CreateUserRequest
    {
        Email = "[email protected]",
        Username = "alex",
        DisplayName = "Alex Example",
        Labels = new Dictionary<string, string> { ["team"] = "search" },
    }
);

GetAsync

Retrieves a user by ID or email address. Exactly one of id and email must be provided.

Declaration

public Task<UserResponse> GetAsync(UsersGetOptions options, CancellationToken ct = default)

HTTP — GET /v1/users/{id}

Parameters

Returns

Task<UserResponse> — an awaitable that resolves to UserResponse.

Exceptions

Examples

Example 1:

var user = await client.Users.GetAsync(new UsersGetOptions { Id = "your-user-id" });
Console.WriteLine(user.Email);

Example 2:

// Or look a user up by email instead of ID.
var user = await client.Users.GetAsync(
    new UsersGetOptions { Email = "[email protected]" }
);
Console.WriteLine(user.UserId);

ListAsync

Requires LIST_USER on the GoodMem instance and READ_USER on each returned row. Authorization, label filtering, lifecycle filtering, and keyset pagination run in PostgreSQL. includeDeleted expands the lifecycle view but grants no access. includeEnrollmentSummary requests non-secret bootstrap posture only on active rows where MANAGE_USER_ENROLLMENT is independently authorized.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

Declaration

public IAsyncEnumerable<UserResponse> ListAsync(UsersListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/users

Parameters

Returns

IAsyncEnumerable<UserResponse> — an async stream; await foreach yields each UserResponse across pages / events.

Exceptions

Example

await foreach (var user in client.Users.ListAsync(new UsersListOptions { MaxResults = 25 }))
    Console.WriteLine($"{user.UserId} {user.Email}");

UpdateAsync

Updates only fields present in the request. Empty username or displayName values clear those optional fields. Updating a deleted user fails with 412.

Declaration

public Task<UserResponse> UpdateAsync(string id, UpdateUserRequest request, CancellationToken ct = default)

HTTP — PUT /v1/users/{id}

Parameters

Returns

Task<UserResponse> — an awaitable that resolves to UserResponse.

Exceptions

Example

var updatedUser = await client.Users.UpdateAsync(
    "your-user-id",
    new UpdateUserRequest { DisplayName = "Alexandra Example" }
);

DeleteAsync

Permanently soft-deletes the user and invalidates credentials acting for that subject. The GoodMem instance owner cannot be deleted; transfer ownership first. Repeating an authorized delete succeeds without rewriting audit data.

Declaration

public Task DeleteAsync(string id, CancellationToken ct = default)

HTTP — DELETE /v1/users/{id}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.Users.DeleteAsync("your-user-id");

CreateEnrollmentAsync

Creates a short-lived, one-time enrollment credential for an existing dormant human. Requires MANAGE_USER_ENROLLMENT with ANY or EXACT authority on the target user. The raw credential is returned only once. rotateExisting atomically revokes and replaces a live enrollment; an expired enrollment is replaced automatically.

Declaration

public Task<CreateUserEnrollmentResponse> CreateEnrollmentAsync(string userId, CreateUserEnrollmentRequest? request = null, CancellationToken ct = default)

HTTP — POST /v1/users/{userId}/enrollments

Parameters

Returns

Task<CreateUserEnrollmentResponse> — an awaitable that resolves to CreateUserEnrollmentResponse.

Exceptions

Example

var createdEnrollment = await client.Users.CreateEnrollmentAsync(
    "your-user-id",
    new CreateUserEnrollmentRequest { RotateExisting = true }
);
// Save createdEnrollment.EnrollmentToken now; it is returned only once.

GetByUsernameAsync

Returns a user selected by exact username after applying READ_USER authority. includeDeleted permits an authorized caller to inspect a permanent tombstone; it does not grant additional authority. Missing and unauthorized matches both return 404 so this guessable identifier cannot reveal whether a user exists.

Declaration

public Task<UserResponse> GetByUsernameAsync(string username, UsersGetByUsernameOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/users/username/{username}

Parameters

Returns

Task<UserResponse> — an awaitable that resolves to UserResponse.

Exceptions

Example

var userByUsername = await client.Users.GetByUsernameAsync("alex");
Console.WriteLine(userByUsername.Email);

GetEnrollmentAsync

Returns non-secret metadata for one current or historical enrollment. The target user is resolved before the enrollment, and MANAGE_USER_ENROLLMENT with ANY or EXACT authority on that user is required. Raw enrollment tokens are never returned.

Declaration

public Task<UserEnrollmentResponse> GetEnrollmentAsync(string userId, string enrollmentId, CancellationToken ct = default)

HTTP — GET /v1/users/{userId}/enrollments/{enrollmentId}

Parameters

Returns

Task<UserEnrollmentResponse> — an awaitable that resolves to UserEnrollmentResponse.

Exceptions

Example

var enrollment = await client.Users.GetEnrollmentAsync(
    "your-user-id",
    "your-enrollment-id"
);

ListEnrollmentsAsync

Returns one newest-first page containing pending, expired, consumed, and revoked enrollment metadata. MANAGE_USER_ENROLLMENT with ANY or EXACT authority on the target user is required. The page never contains raw credentials.

Declaration

public IAsyncEnumerable<UserEnrollmentResponse> ListEnrollmentsAsync(string userId, UsersListEnrollmentsOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/users/{userId}/enrollments

Parameters

Returns

IAsyncEnumerable<UserEnrollmentResponse> — an async stream; await foreach yields each UserEnrollmentResponse across pages / events.

Exceptions

Example

await foreach (var item in client.Users.ListEnrollmentsAsync("your-user-id"))
    Console.WriteLine($"{item.EnrollmentId} {item.Status}");

MeAsync

Returns the human-user profile associated with the authenticated principal. Service principals do not have a human-user profile.

Declaration

public Task<UserResponse> MeAsync(CancellationToken ct = default)

HTTP — GET /v1/users/me

Parameters

Returns

Task<UserResponse> — an awaitable that resolves to UserResponse.

Exceptions

Example

var user = await client.Users.MeAsync();
Console.WriteLine($"{user.Email} {user.UserId}");

RevokeEnrollmentAsync

Permanently revokes one outstanding enrollment after requiring MANAGE_USER_ENROLLMENT on its target user. Repeating an authorized revocation succeeds without replacing its original audit provenance. Consumed enrollments cannot be revoked.

Declaration

public Task RevokeEnrollmentAsync(string userId, string enrollmentId, CancellationToken ct = default)

HTTP — DELETE /v1/users/{userId}/enrollments/{enrollmentId}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.Users.RevokeEnrollmentAsync("your-user-id", "your-enrollment-id");

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

CreateUserRequest

Creates a human user without creating a credential, role assignment, grant, or external authentication mapping.

UserResponse

A durable human user profile and its lifecycle metadata.

UserEnrollmentSummary

Non-secret enrollment posture for one active human user.

CreateUserEnrollmentRequest

Options for issuing a one-time enrollment credential to the user named by the request path.

CreateUserEnrollmentResponse

New enrollment metadata and its one-time raw enrollment credential.

UserEnrollmentResponse

Non-secret lifecycle metadata for a human user's one-time enrollment credential.

ListUsersResponse

One authorization-filtered page of human users.

ListUserEnrollmentsResponse

One stable page of a human user's enrollment history.

UpdateUserRequest

Updates explicitly present profile fields. Empty username or displayName clears that optional field; an omitted field remains unchanged.