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.
ApiKeyAuthx-api-key<token>GoodMem-Timeout-Ms?integerOptional 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.
int641 <= value <= 86400000API key configuration
application/json- body
Request parameters for creating a new API key.
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._-].
properties <= 20{ "purpose": "production", "service": "recommendation-engine"}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.
int641672531200000apiKeyId?|Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
uuid"550e8400-e29b-41d4-a716-446655440000"subjectPrincipalId?|Principal authenticated by this key. Omit to use the authenticated principal.
uuid"70e025f6-76ca-4cbe-b8fc-7dab8e84590a"authorityMode?|Authority mode. Omit to create a self-issued human key that inherits live authority. A scoped issuing credential may create only SCOPED children.
"INHERIT_SUBJECT"ceiling?array<>|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 <= 1000validFrom?|Inclusive activation time in epoch milliseconds. Omit to activate at issuance time.
int641735689600000Successfully created API key with Location header
application/json- response
Response returned when creating a new API key.
apiKeyMetadata?Metadata for the created API key.
rawApiKey?stringThe actual API key value. This is only returned once and cannot be retrieved again.
"gm_12345678901234567890123456789012345678901234567890"curl -X POST 'https://your-goodmem-server.example.com/v1/apikeys' \ -H 'GoodMem-Timeout-Ms: 30000' \ -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"}