API Keys

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

API key lifecycle — create, list, update, soft-delete.

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

Index

• type APIKeysService
  • func (s *APIKeysService) Create
  • func (s *APIKeysService) List
  • func (s *APIKeysService) Update
  • func (s *APIKeysService) Delete
• type CreateApiKeyRequest
• type CreateApiKeyResponse
• type ApiKeyResponse
• type ListApiKeysResponse
• type UpdateApiKeyRequest

type APIKeysService

type APIKeysService struct{ … }

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

func (s *APIKeysService) Create

func (s *APIKeysService) Create(ctx context.Context, req *models.CreateAPIKeyRequest) (*models.CreateAPIKeyResponse, error)

Creates a new API key for authenticating with the API. New keys start in ACTIVE status and can be used immediately for authentication. The response includes the one-time raw API key value which will not be retrievable later - clients must save this value as it cannot be recovered. Requires CREATE_APIKEY_OWN permission (or CREATE_APIKEY_ANY for admin users). Side effects include generating cryptographically secure key material, recording creation timestamp, and tracking creator ID. Returns INVALID_ARGUMENT if expires_at is set to a time in the past.

HTTP — POST /v1/apikeys

Parameters

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

Returns — (*models.CreateAPIKeyResponse, error)

Example

key, err := client.APIKeys().Create(ctx, &models.CreateAPIKeyRequest{
	Labels: map[string]string{"env": "docs", "purpose": "sdk-doc-test"},
})
if err != nil {
	log.Fatal(err)
}
_ = key

func (s *APIKeysService) List

func (s *APIKeysService) List(ctx context.Context) (*models.ListAPIKeysResponse, error)

Retrieves a list of API keys belonging to the authenticated user. The list includes metadata about each key but not the actual key values or key hashes for security reasons. Requires LIST_APIKEY_OWN permission (or LIST_APIKEY_ANY for admin users to view keys from any user). This is a read-only operation with no side effects.

HTTP — GET /v1/apikeys

Parameters

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

Returns — (*models.ListAPIKeysResponse, error)

Example

resp, err := client.APIKeys().List(ctx)
if err != nil {
	log.Fatal(err)
}
for _, key := range resp.Keys {
	_ = key.APIKeyID
	_ = key.Status
}

func (s *APIKeysService) Update

func (s *APIKeysService) Update(ctx context.Context, id string, req *models.UpdateAPIKeyRequest) (*models.APIKeyResponse, error)

Updates an existing API key with new values for status or labels. IMPORTANT: Key ID, user ownership, key material, and audit fields cannot be modified - only status (ACTIVE/INACTIVE) and labels are mutable. Requires UPDATE_APIKEY_OWN permission for keys you own (or UPDATE_APIKEY_ANY for admin users to modify any user's keys). Side effects include updating the updated_at timestamp and recording the updater's user ID. This operation is idempotent - repeated identical requests have no additional effect.

HTTP — PUT /v1/apikeys/{id}

Parameters

• ctx (context.Context) — carries the deadline and cancellation signal for the call.
• id (string) — The UUID of the API key to update
• req (*models.UpdateAPIKeyRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.APIKeyResponse, error)

Example

updated, err := client.APIKeys().Update(ctx, "your-api-key-id", &models.UpdateAPIKeyRequest{
	MergeLabels: map[string]string{"updated": "true"},
})
if err != nil {
	log.Fatal(err)
}
_ = updated.APIKeyID

func (s *APIKeysService) Delete

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

Delete an API key

Permanently deletes an API key. This operation cannot be undone and immediately invalidates the key for all future authentication attempts. TIP: For reversible deactivation, use PUT /v1/apikeys/{id} with status=INACTIVE instead. Requires DELETE_APIKEY_OWN permission for keys you own (or DELETE_APIKEY_ANY for admin users to delete any user's keys). Side effects include permanently removing the key record from the database and immediate authentication invalidation.

HTTP — DELETE /v1/apikeys/{id}

Parameters

• ctx (context.Context) — carries the deadline and cancellation signal for the call.
• id (string) — The UUID of the API key to delete

Returns — error — nil on success.

Example

err := client.APIKeys().Delete(ctx, "your-api-key-id")
if err != nil {
	log.Fatal(err)
}

type CreateApiKeyRequest

type CreateApiKeyRequest struct{ … }

Request parameters for creating a new API key.

• Labels (map[string]string, optional, wire labels) — Key-value pairs of metadata associated with the API key. Used for organization and filtering.
• ExpiresAt (int64, optional, wire expiresAt) — Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
• APIKeyID (string, optional, wire apiKeyId) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

type CreateApiKeyResponse

type CreateApiKeyResponse struct{ … }

Response returned when creating a new API key.

• APIKeyMetadata (models.ApiKeyResponse, optional, wire apiKeyMetadata) — Metadata for the created API key.
• RawAPIKey (string, optional, wire rawApiKey) — The actual API key value. This is only returned once and cannot be retrieved again.

type ApiKeyResponse

type ApiKeyResponse struct{ … }

API key metadata without sensitive information.

• APIKeyID (string, wire apiKeyId) — Unique identifier for the API key.
• UserID (string, wire userId) — ID of the user that owns this API key.
• KeyPrefix (string, wire keyPrefix) — First few characters of the key for display/identification purposes.
• Status (string, wire status) — Current status of the API key: ACTIVE, INACTIVE, or STATUS_UNSPECIFIED.
• Labels (map[string]string, wire labels) — User-defined labels for organization and filtering.
• ExpiresAt (int64, optional, wire expiresAt) — Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
• LastUsedAt (int64, optional, wire lastUsedAt) — Last time this API key was used, in milliseconds since epoch.
• CreatedAt (int64, wire createdAt) — When the API key was created, in milliseconds since epoch.
• UpdatedAt (int64, wire updatedAt) — When the API key was last updated, in milliseconds since epoch.
• CreatedByID (string, wire createdById) — ID of the user that created this API key.
• UpdatedByID (string, wire updatedById) — ID of the user that last updated this API key.

type ListApiKeysResponse

type ListApiKeysResponse struct{ … }

Response containing a list of API keys.

• Keys ([]models.ApiKeyResponse, wire keys) — List of API keys belonging to the authenticated user.

type UpdateApiKeyRequest

type UpdateApiKeyRequest struct{ … }

Request parameters for updating an API key.

• Status (string, optional, wire status) — New status for the API key. Allowed values: ACTIVE, INACTIVE.
• ReplaceLabels (map[string]string, optional, wire replaceLabels) — Replace all existing labels with this set. Mutually exclusive with mergeLabels.
• MergeLabels (map[string]string, optional, wire mergeLabels) — Merge these labels with existing ones. Mutually exclusive with replaceLabels.