Users

Go SDK reference for human users: enrollment management, creation, lookup, listing, updates, and deletion.

package goodmem // import "fury.io/pairsys/goodmem"

User lookup by id, email, or me.

Methods are called as client.Users().<Method>(ctx, ...) on a *goodmem.Client. Service: UsersService.

Index

type UsersService
type CreateUserRequest
type UserResponse
type UserEnrollmentSummary
type CreateUserEnrollmentRequest
type CreateUserEnrollmentResponse
type UserEnrollmentResponse
type ListUsersResponse
type ListUserEnrollmentsResponse
type UpdateUserRequest

type UsersService

type UsersService struct{ … }

Access this service as client.Users() on a *goodmem.Client. Its methods follow.

func (s *UsersService) Create

func (s *UsersService) Create(ctx context.Context, req *models.CreateUserRequest) (*models.UserResponse, error)

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.

HTTP — POST /v1/users

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.CreateUserRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.UserResponse, error)

Example

createdUser, err := client.Users().Create(ctx, &models.CreateUserRequest{
	Email:       "[email protected]",
	Username:    goodmem.Ptr("alex"),
	DisplayName: goodmem.Ptr("Alex Example"),
	Labels:      map[string]string{"team": "search"},
})
if err != nil {
	log.Fatal(err)
}
_ = createdUser.UserID

func (s *UsersService) Get

func (s *UsersService) Get(ctx context.Context, opts *UsersGetOptions) (*models.UserResponse, error)

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

HTTP — GET /v1/users/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
opts (*UsersGetOptions) — options bag carrying the lookup key(s) / convenience knobs; set only the fields you need.

Returns — (*models.UserResponse, error)

Examples

Example 1:

user, err := client.Users().Get(ctx, &goodmem.UsersGetOptions{ID: goodmem.Ptr("your-user-id")})
if err != nil {
	log.Fatal(err)
}
_ = user.Email

Example 2:

user, err := client.Users().Get(ctx, &goodmem.UsersGetOptions{Email: goodmem.Ptr("[email protected]")})
if err != nil {
	log.Fatal(err)
}
_ = user.UserID

func (s *UsersService) List

func (s *UsersService) List(ctx context.Context, params *UsersListParams) (*Page[models.UserResponse], error)

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

HTTP — GET /v1/users

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
params (*UsersListParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*Page[models.UserResponse], error)

Example

users, err := client.Users().List(ctx, &goodmem.UsersListParams{
	MaxResults: goodmem.Ptr(int32(25)),
})
if err != nil {
	log.Fatal(err)
}
for _, user := range users.Items() {
	_ = user.Email
}

func (s *UsersService) Update

func (s *UsersService) Update(ctx context.Context, id string, req *models.UpdateUserRequest) (*models.UserResponse, error)

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

HTTP — PUT /v1/users/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — User UUID
req (*models.UpdateUserRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.UserResponse, error)

Example

updatedUser, err := client.Users().Update(ctx, "your-user-id", &models.UpdateUserRequest{
	DisplayName: goodmem.Ptr("Alexandra Example"),
})
if err != nil {
	log.Fatal(err)
}
_ = updatedUser.DisplayName

func (s *UsersService) Delete

func (s *UsersService) Delete(ctx context.Context, id string) error

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.

HTTP — DELETE /v1/users/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — User UUID

Returns — error — nil on success.

Example

deleteUserErr := client.Users().Delete(ctx, "your-user-id")
if deleteUserErr != nil {
	log.Fatal(deleteUserErr)
}

func (s *UsersService) CreateEnrollment

func (s *UsersService) CreateEnrollment(ctx context.Context, userID string, req *models.CreateUserEnrollmentRequest) (*models.CreateUserEnrollmentResponse, error)

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.

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

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
userID (string) — Human-user UUID
req (*models.CreateUserEnrollmentRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.CreateUserEnrollmentResponse, error)

Example

createdEnrollment, err := client.Users().CreateEnrollment(
	ctx,
	"your-user-id",
	&models.CreateUserEnrollmentRequest{RotateExisting: goodmem.Ptr(true)},
)
if err != nil {
	log.Fatal(err)
}
// Save createdEnrollment.EnrollmentToken now; it is returned only once.
_ = createdEnrollment.EnrollmentToken

func (s *UsersService) GetByUsername

func (s *UsersService) GetByUsername(ctx context.Context, username string, params *UsersGetByUsernameParams) (*models.UserResponse, error)

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.

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

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
username (string) — Exact username
params (*UsersGetByUsernameParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.UserResponse, error)

Example

userByUsername, err := client.Users().GetByUsername(ctx, "alex", nil)
if err != nil {
	log.Fatal(err)
}
_ = userByUsername.Email

func (s *UsersService) GetEnrollment

func (s *UsersService) GetEnrollment(ctx context.Context, userID string, enrollmentID string) (*models.UserEnrollmentResponse, error)

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.

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

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
userID (string) — Human-user UUID
enrollmentID (string) — Enrollment UUID

Returns — (*models.UserEnrollmentResponse, error)

Example

enrollment, err := client.Users().GetEnrollment(
	ctx,
	"your-user-id",
	"your-enrollment-id",
)
if err != nil {
	log.Fatal(err)
}
_ = enrollment.Status

func (s *UsersService) ListEnrollments

func (s *UsersService) ListEnrollments(ctx context.Context, userID string, params *UsersListEnrollmentsParams) (*Page[models.UserEnrollmentResponse], error)

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.

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

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
userID (string) — Human-user UUID
params (*UsersListEnrollmentsParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*Page[models.UserEnrollmentResponse], error)

Example

enrollments, err := client.Users().ListEnrollments(ctx, "your-user-id", nil)
if err != nil {
	log.Fatal(err)
}
for _, enrollment := range enrollments.Items() {
	_ = enrollment.Status
}

func (s *UsersService) Me

func (s *UsersService) Me(ctx context.Context) (*models.UserResponse, error)

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

HTTP — GET /v1/users/me

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.

Returns — (*models.UserResponse, error)

Example

user, err := client.Users().Me(ctx)
if err != nil {
	log.Fatal(err)
}
_ = user.Email

func (s *UsersService) RevokeEnrollment

func (s *UsersService) RevokeEnrollment(ctx context.Context, userID string, enrollmentID string) error

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.

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

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
userID (string) — Human-user UUID
enrollmentID (string) — Enrollment UUID

Returns — error — nil on success.

Example

revokeErr := client.Users().RevokeEnrollment(
	ctx,
	"your-user-id",
	"your-enrollment-id",
)
if revokeErr != nil {
	log.Fatal(revokeErr)
}

type CreateUserRequest

type CreateUserRequest struct{ … }

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

UserID (string, optional, wire userId) — Optional client-provided user UUID; generated by the server when omitted.
Email (string, wire email) — Unique, nonempty email address.
Username (string, optional, wire username) — Optional unique username.
DisplayName (string, optional, wire displayName) — Optional human-facing display name.
Labels (map[string]string, optional, wire labels) — Optional labels for organization and filtering. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].

type UserResponse

type UserResponse struct{ … }

A durable human user profile and its lifecycle metadata.

UserID (string, wire userId) — OUTPUT_ONLY; immutable user UUID.
Email (string, wire email) — OUTPUT_ONLY; unique email address.
DisplayName (string, optional, wire displayName) — OUTPUT_ONLY; optional human-facing display name.
Username (string, optional, wire username) — OUTPUT_ONLY; optional unique username.
Labels (map[string]string, wire labels) — OUTPUT_ONLY; mutable labels attached to the user principal. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
EnrollmentSummary (models.UserEnrollmentSummary, optional, wire enrollmentSummary) — OUTPUT_ONLY; enrollment posture when requested and independently authorized.
DeletedAt (int64, optional, wire deletedAt) — OUTPUT_ONLY; permanent deletion time in milliseconds, absent while active.
DeletedByID (string, optional, wire deletedById) — OUTPUT_ONLY; exact deleting actor UUID, absent while active.
CreatedAt (int64, wire createdAt) — OUTPUT_ONLY; creation time in milliseconds since the epoch.
UpdatedAt (int64, wire updatedAt) — OUTPUT_ONLY; most recent mutation time in milliseconds since the epoch.
CreatedByID (string, wire createdById) — OUTPUT_ONLY; exact creating actor UUID.
UpdatedByID (string, wire updatedById) — OUTPUT_ONLY; exact actor UUID for the most recent mutation.

type UserEnrollmentSummary

type UserEnrollmentSummary struct{ … }

Non-secret enrollment posture for one active human user.

BootstrapEligible (bool, wire bootstrapEligible) — Whether no enrollment has been consumed and the user has no subject API key.
OpenEnrollmentStatus (string, optional, wire openEnrollmentStatus) — State of the open enrollment, when one exists; present exactly with openEnrollmentExpiresAt.
OpenEnrollmentExpiresAt (int64, optional, wire openEnrollmentExpiresAt) — Exclusive open-enrollment completion deadline in epoch milliseconds; present exactly with openEnrollmentStatus.

type CreateUserEnrollmentRequest

type CreateUserEnrollmentRequest struct{ … }

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

EnrollmentID (string, optional, wire enrollmentId) — Optional client-provided enrollment UUID; generated when omitted.
RotateExisting (bool, optional, wire rotateExisting) — Whether an existing live enrollment may be revoked and atomically replaced.

type CreateUserEnrollmentResponse

type CreateUserEnrollmentResponse struct{ … }

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

Enrollment (models.UserEnrollmentResponse, wire enrollment) — OUTPUT_ONLY; non-secret metadata for the created enrollment.
EnrollmentToken (string, wire enrollmentToken) — OUTPUT_ONLY; one-time raw enrollment credential. Save and deliver it securely.

type UserEnrollmentResponse

type UserEnrollmentResponse struct{ … }

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

EnrollmentID (string, wire enrollmentId) — OUTPUT_ONLY; immutable enrollment UUID.
UserID (string, wire userId) — OUTPUT_ONLY; UUID of the human user invited to enroll.
CredentialPrefix (string, wire credentialPrefix) — OUTPUT_ONLY; non-secret prefix that identifies the enrollment credential safely.
Status (string, wire status) — OUTPUT_ONLY; current derived enrollment lifecycle state.
ExpiresAt (int64, wire expiresAt) — OUTPUT_ONLY; exclusive completion deadline in milliseconds since epoch.
ConsumedAPIKeyID (string, optional, wire consumedApiKeyId) — OUTPUT_ONLY; initial API-key UUID, present after consumption.
CreatedAt (int64, wire createdAt) — OUTPUT_ONLY; enrollment issuance time in milliseconds since epoch.
ConsumedAt (int64, optional, wire consumedAt) — OUTPUT_ONLY; first-completion time, absent before consumption.
RevokedAt (int64, optional, wire revokedAt) — OUTPUT_ONLY; permanent revocation time, absent while unrevoked.
CreatedByID (string, wire createdById) — OUTPUT_ONLY; exact principal or API-key actor that issued the enrollment.
RevokedByID (string, optional, wire revokedById) — OUTPUT_ONLY; exact revoking actor UUID, absent while unrevoked.

type ListUsersResponse

type ListUsersResponse struct{ … }

One authorization-filtered page of human users.

Users ([]models.UserResponse, wire users) — OUTPUT_ONLY; users in stable keyset order.
NextToken (string, optional, wire nextToken) — OUTPUT_ONLY; opaque continuation token, omitted after the final page.

type ListUserEnrollmentsResponse

type ListUserEnrollmentsResponse struct{ … }

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

Enrollments ([]models.UserEnrollmentResponse, wire enrollments) — OUTPUT_ONLY; enrollments ordered newest first.
NextToken (string, optional, wire nextToken) — OUTPUT_ONLY; opaque continuation token, absent after the final page.

type UpdateUserRequest

type UpdateUserRequest struct{ … }

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

Email (string, optional, wire email) — Replacement email. A present empty value is invalid.
Username (string, optional, wire username) — Replacement username. An empty string clears the username.
DisplayName (string, optional, wire displayName) — Replacement display name. An empty string clears the display name.
ReplaceLabels (map[string]string, optional, wire replaceLabels) — Complete replacement label map; an empty map clears all labels and is mutually exclusive with mergeLabels. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
MergeLabels (map[string]string, optional, wire mergeLabels) — Labels to upsert; must contain at least one entry and is mutually exclusive with replaceLabels. The final stored map may contain at most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

On this page