GoodMemCreate a new API key
POST /v1/apikeys: Issues a new API key and returns its raw value exactly once.
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.
In: header
API key configuration
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._-].
{"purpose":"production","service":"recommendation-engine"}properties <= 20Empty Object
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.
1672531200000int64Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
"550e8400-e29b-41d4-a716-446655440000"uuidPrincipal authenticated by this key. Omit to use the authenticated principal.
"70e025f6-76ca-4cbe-b8fc-7dab8e84590a"uuidAuthority mode. Omit to create a self-issued human key that inherits live authority. A scoped issuing credential may create only SCOPED children.
"INHERIT_SUBJECT"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.
items <= 1000Inclusive activation time in epoch milliseconds. Omit to activate at issuance time.
1735689600000int64Response Body
curl -X POST "https://your-goodmem-server.example.com/v1/apikeys" \ -H "Content-Type: application/json" \ -d '{ "labels": { "purpose": "production", "service": "chat-ui", "environment": "development" }, "expiresAt": 1735689600000, "apiKeyId": "550e8400-e29b-41d4-a716-446655440000", "subjectPrincipalId": "70e025f6-76ca-4cbe-b8fc-7dab8e84590a", "ceiling": [ { "assignedResource": { "resourceId": "550e8400-e29b-41d4-a716-446655440000" } } ], "validFrom": 1735689600000, "authorityMode": "INHERIT_SUBJECT" }'{
"apiKeyMetadata": {
"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"
},
"rawApiKey": "gm_12345678901234567890123456789012345678901234567890"
}