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) Get
  • func (s *APIKeysService) List
  • func (s *APIKeysService) Update
  • func (s *APIKeysService) Delete
• type CreateApiKeyRequest
• type CreateApiKeyResponse
• 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)

Issues a new API key and returns its raw value exactly once. Omitted subject and authorityMode create a self-issued human key that inherits the subject's live authority. A SCOPED key requires a nonempty immutable ceiling, and every ceiling rule must be conservatively covered by both the subject's live authority and the issuing credential's effective authority. A scoped issuer can create only scoped children. SERVICE subjects require SCOPED mode and MANAGE_ACCESS on the service identity.

AUTHORIZATION: Requires CREATE_API_KEY on the proposed credential; subject and ceiling checks are repeated by the final insertion statement.

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

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

Returns complete non-secret metadata for one existing credential after requiring effective READ_API_KEY authority. The immutable ceiling is always complete and ceilingOmitted is false. Raw key material and hashes are never returned.

HTTP — GET /v1/apikeys/{id}

Parameters

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

Returns — (*models.APIKeyResponse, error)

Example

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

func (s *APIKeysService) List

func (s *APIKeysService) List(ctx context.Context, params *APIKeysListParams) (*Page[models.APIKeyResponse], error)

Requires LIST_API_KEY on the singleton instance, then retrieves one UUID-ordered page containing only credentials that independently pass READ_API_KEY. Both gates use the authenticated principal's live authority and any scoped-key ceiling. Subject, owner, and lifecycle filters are applied after authorization. FULL includes complete immutable ceilings; BASIC omits them, sets ceilingOmitted=true, and permits larger pages. Raw key values and key hashes are never returned.

HTTP — GET /v1/apikeys

Parameters

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

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

Example

page, err := client.APIKeys().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for key, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	_ = 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's labels or lifecycle status. Key ID, subject, ownership, key material, validity window, and creation audit fields remain immutable. Label changes require UPDATE_API_KEY; setting status=INACTIVE permanently revokes the key and requires DELETE_API_KEY; a request doing both requires both operations. Revoked keys cannot be reactivated. Side effects include updating administrative audit fields and, for revocation, recording the revocation time and actor.

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 revokes an API key and immediately rejects it for future authentication. The durable credential and audit history remain stored. This operation requires DELETE_API_KEY and records the revocation time and actor; it cannot be undone. PUT /v1/apikeys/{id} with status=INACTIVE performs the same permanent revocation.

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. At most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
• ExpiresAt (int64, optional, wire expiresAt) — Exclusive expiration timestamp in milliseconds since epoch. It must be later than validFrom, which defaults to issuance time; if omitted, 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.
• SubjectPrincipalID (string, optional, wire subjectPrincipalId) — Principal authenticated by this key. Omit to use the authenticated principal.
• AuthorityMode (models.ApiKeyAuthorityMode, optional, wire authorityMode) — Authority mode. Omit to create a self-issued human key that inherits live authority. A scoped issuing credential may create only SCOPED children.
• Ceiling ([]models.AccessPolicyRule, optional, wire ceiling) — Immutable authorization ceiling. Required and nonempty for SCOPED; omitted for INHERIT_SUBJECT, with at most 1,000 rules. Every rule must be covered by both the subject's live authority and the issuing credential's effective authority.
• ValidFrom (int64, optional, wire validFrom) — Inclusive activation time in epoch milliseconds. Omit to activate at issuance time.

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 ListApiKeysResponse

type ListApiKeysResponse struct{ … }

One page of API keys discoverable to the authenticated principal.

• Keys ([]models.ApiKeyResponse, wire keys) — API keys in stable UUID order.
• NextToken (string, optional, wire nextToken) — Opaque token for retrieving the next page; omitted on the last page.

type UpdateApiKeyRequest

type UpdateApiKeyRequest struct{ … }

Request parameters for updating an API key.

• Status (string, optional, wire status) — New status for the API key. INACTIVE is permanent; revoked keys cannot be reactivated.
• ReplaceLabels (map[string]string, optional, wire replaceLabels) — Replace all existing labels with this set. Mutually exclusive with mergeLabels. The stored map may contain at most 20 entries; keys and values contain at most 255 characters; keys use [a-z0-9._-].
• MergeLabels (map[string]string, optional, wire mergeLabels) — Merge these labels with existing ones. 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._-].