Update an API key

PUT

/v1/apikeys/{id}

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.

Authorization

ApiKeyAuth

headerx-api-key<token>

Path Parameters

id*string

The UUID of the API key to update

Header Parameters

GoodMem-Timeout-Ms?integer

Optional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.

Formatint64

Range1 <= value <= 86400000

Request Body

API key update details

application/json

body

Request parameters for updating an API key.

status?|

New status for the API key. INACTIVE is permanent; revoked keys cannot be reactivated.

Example"ACTIVE"

Value in"ACTIVE""INACTIVE"

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._-].

Propertiesproperties <= 20

Example

{  "environment": "production",  "service": "recommendation-engine"}

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._-].

Propertiesproperties <= 20

Example

{  "team": "ml-research"}

Response Body

Successfully updated API key

application/json

response

API key metadata without sensitive information.

apiKeyId*string

Unique identifier for the API key.

Formatuuid

Example"550e8400-e29b-41d4-a716-446655440000"

subjectPrincipalId*string

Principal authenticated by this API key.

Formatuuid

Example"70e025f6-76ca-4cbe-b8fc-7dab8e84590a"

ownerPrincipalId*string

Principal that administratively owns this API key.

Formatuuid

Example"b3303d0a-1a4a-493f-b9bf-38e37153b5a2"

authorityMode*ApiKeyAuthorityMode

Immutable authority derivation mode.

Value in"INHERIT_SUBJECT""SCOPED"

ceiling?array<>|

Complete immutable issuance ceiling; omitted only when ceilingOmitted is true.

ceilingOmitted*boolean

True only when a BASIC list projection intentionally omitted the immutable ceiling.

keyPrefix*string

First few characters of the key for display/identification purposes.

Example"gm_12345..."

status*string

Compatibility usability status. ACTIVE means USABLE; INACTIVE combines NOT_YET_VALID, EXPIRED, and REVOKED.

Example"ACTIVE"

Value in"ACTIVE""INACTIVE"

lifecycleState*string

Precise lifecycle state at the response evaluation instant.

Value in"NOT_YET_VALID""USABLE""EXPIRED""REVOKED"

labels*

User-defined labels for organization and filtering.

Example

{  "purpose": "production",  "service": "recommendation-engine"}

expiresAt?|

Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.

Formatint64

Example1672531200000

validFrom*integer

Inclusive activation time in milliseconds since epoch.

Formatint64

Example1640908800000

revokedAt?|

Permanent revocation time in milliseconds since epoch.

Formatint64

Example1640995200000

revokedById?|

Exact audit actor UUID that revoked this key.

Formatuuid

Example"b3303d0a-1a4a-493f-b9bf-38e37153b5a2"

lastUsedAt?|

Last time this API key was used, in milliseconds since epoch.

Formatint64

Example1640995200000

createdAt*integer

When the API key was created, in milliseconds since epoch.

Formatint64

Example1640908800000

updatedAt*integer

When the API key was last updated, in milliseconds since epoch.

Formatint64

Example1640908800000

createdById*string

Exact principal or API-key actor that created this API key.

Formatuuid

Example"b3303d0a-1a4a-493f-b9bf-38e37153b5a2"

updatedById*string

Exact principal or API-key actor that last updated this API key.

Formatuuid

Example"b3303d0a-1a4a-493f-b9bf-38e37153b5a2"

Example Request

curl -X PUT 'https://your-goodmem-server.example.com/v1/apikeys/550e8400-e29b-41d4-a716-446655440000' \  -H 'GoodMem-Timeout-Ms: 30000' \  -H 'Content-Type: application/json' \  -d '{  "status": "ACTIVE",  "replaceLabels": {    "environment": "production",    "service": "recommendation-engine"  },  "mergeLabels": {    "team": "ml-research"  }}'

Example ResponseSchema

{  "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",  "subjectPrincipalId": "70e025f6-76ca-4cbe-b8fc-7dab8e84590a",  "ownerPrincipalId": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",  "authorityMode": "INHERIT_SUBJECT",  "ceiling": [    {      "assignedResource": {        "resourceId": "550e8400-e29b-41d4-a716-446655440000"      }    }  ],  "ceilingOmitted": true,  "keyPrefix": "gm_12345...",  "status": "ACTIVE",  "lifecycleState": "NOT_YET_VALID",  "labels": {    "purpose": "production",    "service": "recommendation-engine"  },  "expiresAt": 1672531200000,  "validFrom": 1640908800000,  "revokedAt": 1640995200000,  "revokedById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",  "lastUsedAt": 1640995200000,  "createdAt": 1640908800000,  "updatedAt": 1640908800000,  "createdById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",  "updatedById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2"}

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Path Parameters

Header Parameters

Request Body

Response Body