Service Identities

Production service identity lifecycle.

Methods on this page are called through client.service_identities.

client.service_identities.create

client.service_identities.create(request: CreateServiceIdentityRequest, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>

Creates one production-workload identity owned by the authenticated human. No API key, role, grant, or authentication mapping is created implicitly.

HTTP: POST /v1/service-identities

Parameters

Returns: Promise<ServiceIdentityResponseShape>

Example

const identity = await client.serviceIdentities.create({
  displayName: "production-indexer",
  description: "Indexes newly uploaded memories",
  labels: { environment: "production" },
});

client.service_identities.delete

client.service_identities.delete(id: string, requestOptions?: RequestOptions): Promise<void>

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.

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

Parameters

Returns: Promise<void>

Example

await client.serviceIdentities.delete(
  transferredIdentity.serviceIdentity.serviceIdentityId,
);

client.service_identities.get

client.service_identities.get(id: string, options?: ServiceIdentitiesGetOptions, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>

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.

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

Parameters

Returns: Promise<ServiceIdentityResponseShape>

Example

const fetchedIdentity = await client.serviceIdentities.get(identity.serviceIdentityId);

client.service_identities.list

client.service_identities.list(options?: ServiceIdentitiesListOptions, requestOptions?: RequestOptions): Promise<Page<ServiceIdentityResponseShape>>

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).

HTTP: GET /v1/service-identities

Parameters

Returns: Promise<Page<ServiceIdentityResponseShape>>

Example

for await (const item of await client.serviceIdentities.list({ maxResults: 25 })) {
  console.log(item.serviceIdentityId, item.displayName);
}

client.service_identities.transferOwnership

client.service_identities.transferOwnership(id: string, request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferServiceIdentityOwnershipResponseShape>

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.

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

Parameters

Returns: Promise<TransferServiceIdentityOwnershipResponseShape>

Example

const transferredIdentity = await client.serviceIdentities.transferOwnership(
  updatedIdentity.serviceIdentityId,
  { newOwnerId: "70e025f6-76ca-4cbe-b8fc-7dab8e84590a" },
);

client.service_identities.update

client.service_identities.update(id: string, request: UpdateServiceIdentityRequest, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>

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

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

Parameters

Returns: Promise<ServiceIdentityResponseShape>

Example

const updatedIdentity = await client.serviceIdentities.update(
  fetchedIdentity.serviceIdentityId,
  { description: "Indexes production knowledge sources" },
);

Data Models

Interfaces

CreateServiceIdentityRequest

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

ListServiceIdentitiesResponse

One authorization-filtered page of service identities.

ServiceIdentityResponse

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

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.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

ListServiceIdentitiesResponseShape

ServiceIdentityResponseShape

TransferServiceIdentityOwnershipResponseShape