Service Identities

Production service identity creation, ownership, and lifecycle.

Namespace: Goodmem.Client.Api · Class: ServiceIdentitiesApi

Reach this surface as client.ServiceIdentities 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 production-workload identity owned by the authenticated human. No API key, role, grant, or authentication mapping is created implicitly.

Declaration

public Task<ServiceIdentityResponse> CreateAsync(CreateServiceIdentityRequest request, CancellationToken ct = default)

HTTP — POST /v1/service-identities

Parameters

Returns

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

Exceptions

Example

var identity = await client.ServiceIdentities.CreateAsync(
    new CreateServiceIdentityRequest
    {
        DisplayName = "production-indexer",
        Description = "Indexes newly uploaded memories",
        Labels = new Dictionary<string, string> { ["environment"] = "production" },
    }
);

GetAsync

Returns a service identity after applying READ_SERVICE_IDENTITY authority. includeDeleted permits an authorized caller to inspect a permanent tombstone; it does not grant additional authority.

Declaration

public Task<ServiceIdentityResponse> GetAsync(string id, ServiceIdentitiesGetOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/service-identities/{id}

Parameters

Returns

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

Exceptions

Example

var fetchedIdentity = await client.ServiceIdentities.GetAsync("your-service-identity-id");

ListAsync

Requires LIST_SERVICE_IDENTITY on the GoodMem instance and READ_SERVICE_IDENTITY on each returned row. Owner and label filters, lifecycle filtering, authorization, and keyset pagination execute in PostgreSQL. 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<ServiceIdentityResponse> ListAsync(ServiceIdentitiesListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/service-identities

Parameters

Returns

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

Exceptions

Example

await foreach (
    var item in client.ServiceIdentities.ListAsync(
        new ServiceIdentitiesListOptions { MaxResults = 25 }
    )
)
    Console.WriteLine($"{item.ServiceIdentityId} {item.DisplayName}");

UpdateAsync

Updates only fields present in the request. Empty description clears that optional field. Ownership changes use the dedicated transfer endpoint.

Declaration

public Task<ServiceIdentityResponse> UpdateAsync(string id, UpdateServiceIdentityRequest request, CancellationToken ct = default)

HTTP — PUT /v1/service-identities/{id}

Parameters

Returns

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

Exceptions

Example

var updatedIdentity = await client.ServiceIdentities.UpdateAsync(
    "your-service-identity-id",
    new UpdateServiceIdentityRequest
    {
        Description = "Indexes production knowledge sources",
    }
);

DeleteAsync

Permanently soft-deletes the principal. Its stored credentials remain audit records but can no longer authenticate because their subject is deleted. Repeating an authorized delete succeeds without rewriting audit data.

Declaration

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

HTTP — DELETE /v1/service-identities/{id}

Parameters

Returns

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

Exceptions

Example

await client.ServiceIdentities.DeleteAsync("your-service-identity-id");

TransferOwnershipAsync

Transfers administrative ownership to another active principal. A service identity cannot own itself. The service identity's subject, immutable creator, credentials, grants, and roles are unchanged.

Declaration

public Task<TransferServiceIdentityOwnershipResponse> TransferOwnershipAsync(string id, TransferOwnershipRequest request, CancellationToken ct = default)

HTTP — POST /v1/service-identities/{id}:transferOwnership

Parameters

Returns

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

Exceptions

Example

var transferredIdentity = await client.ServiceIdentities.TransferOwnershipAsync(
    "your-service-identity-id",
    new TransferOwnershipRequest
    {
        NewOwnerId = "your-new-owner-principal-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.

CreateServiceIdentityRequest

Creates a service identity owned by the authenticated human. It does not create credentials, roles, or grants.

ServiceIdentityResponse

A durable production workload identity. Credentials, grants, and roles are separate resources and are not included.

ListServiceIdentitiesResponse

One authorization-filtered page of service identities.

TransferServiceIdentityOwnershipResponse

The service identity after its administrative ownership transfer.

UpdateServiceIdentityRequest

Updates explicitly present profile fields. Empty description clears it; omitted fields remain unchanged. Ownership is changed only through the transfer endpoint.