List Keys Retrieve a paginated list of all keys with optional filtering.
Query Parameters Maximum number of keys to return
Bookmark for cursor-based pagination
Filter expression for keys (e.g., engine_id[eq]golang, algorithm[eq]RSA, tags[contains]production)
Response Bookmark for retrieving the next page of results
Array of key objects Unique identifier for the key
Alternative names for the key
ID of the crypto engine managing this key
Indicates if the private key is available
Cryptographic algorithm: RSA, ECDSA, or Ed25519
Base64 encoded public key
Timestamp when the key was created
Tags for categorization and filtering
Additional metadata as key-value pairs
Example Request curl -X GET "https://api.lamassu.io/api/kms/v1/keys?limit=10&filter=algorithm[eq]RSA" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Example Response { "next_bookmark" : "eyJrZXlfaWQiOiJrZXktMTIzIn0=" , "list" : [ { "key_id" : "key-123e4567-e89b-12d3-a456-426614174000" , "pkcs11_uri" : "pkcs11:token-id=engine1;id=key123;type=private" , "name" : "my-signing-key" , "aliases" : [ "prod-key" , "primary-key" ], "engine_id" : "aws-kms-prod" , "has_private_key" : true , "algorithm" : "RSA" , "size" : 2048 , "public_key" : "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0..." , "creation_ts" : "2025-11-07T10:00:00Z" , "tags" : [ "production" , "signing" ], "metadata" : { "department" : "security" , "owner" : "admin" } } ] }
Create Key Create a new cryptographic key with specified algorithm and size.
Request Body Cryptographic algorithm: RSA, ECDSA, or Ed25519
Key size in bits:
RSA: 2048, 3072, 4096
ECDSA: 256 (P-256), 384 (P-384), 521 (P-521)
Ed25519: (size ignored)
ID of the crypto engine to create the key in
Human-readable name for the key
Array of tags for categorization
Additional metadata as key-value pairs
Response Returns the created key object with generated key_id and public key.
Example Request curl -X POST "https://api.lamassu.io/api/kms/v1/keys" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "algorithm": "RSA", "size": 2048, "engine_id": "aws-kms-prod", "name": "my-new-signing-key", "tags": ["production", "signing"], "metadata": { "purpose": "certificate-signing", "owner": "pki-team" } }'
Example Response { "key_id" : "key-789abc12-def3-45gh-ij67-klmnopqrstuv" , "pkcs11_uri" : "pkcs11:token-id=aws-kms-prod;id=key789;type=private" , "name" : "my-new-signing-key" , "aliases" : [], "engine_id" : "aws-kms-prod" , "has_private_key" : true , "algorithm" : "RSA" , "size" : 2048 , "public_key" : "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0..." , "creation_ts" : "2025-11-08T14:30:00Z" , "tags" : [ "production" , "signing" ], "metadata" : { "purpose" : "certificate-signing" , "owner" : "pki-team" } }
Import Key Import an existing private key into the KMS.
Request Body Base64 encoded private key in PEM or DER format
ID of the crypto engine to import the key into
Human-readable name for the key
Array of tags for categorization
Additional metadata as key-value pairs
Response Returns the imported key object.
Example Request # First, encode your private key to base64 BASE64_KEY = $( cat private-key.pem | base64 -w 0 ) curl -X POST "https://api.lamassu.io/api/kms/v1/keys/import" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "private_key": "'" $BASE64_KEY "'", "engine_id": "golang", "name": "imported-legacy-key", "tags": ["imported", "legacy"], "metadata": { "source": "legacy-system", "imported_date": "2025-11-08" } }'
Get Key by ID Retrieve detailed information about a specific key.
Example Request curl -X GET "https://api.lamassu.io/api/kms/v1/keys/key-123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Delete Key Delete a key from the KMS.
This operation is irreversible. Ensure you have backups or that the key is no longer needed before deletion.
Response Example Request curl -X DELETE "https://api.lamassu.io/api/kms/v1/keys/key-123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Update Key Name Update the human-readable name of a key.
Request Body Example Request curl -X PUT "https://api.lamassu.io/api/kms/v1/keys/key-123/name" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "updated-key-name" }'
Update the tags associated with a key.
Request Body New set of tags for the key (replaces all existing tags)
Example Request curl -X PUT "https://api.lamassu.io/api/kms/v1/keys/key-123/tags" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tags": ["production", "updated", "v2", "critical"] }'
Update Key Aliases Update the aliases for a key using JSON Patch operations.
Request Body Array of JSON Patch operations Operation type: add, remove, replace, move, copy, or test
JSON Pointer path to the field
Source path for move/copy operations
Example Request curl -X PUT "https://api.lamassu.io/api/kms/v1/keys/key-123/alias" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "patches": [ { "op": "add", "path": "/-", "value": "new-alias" } ] }'
Update the metadata of a key using JSON Patch operations.
Request Body Array of JSON Patch operations (RFC 6902) Operation type: add, remove, replace, move, copy, or test
JSON Pointer path (e.g., /metadata/owner, /metadata/department)
Source path for move/copy operations
Example Request curl -X PUT "https://api.lamassu.io/api/kms/v1/keys/key-123/metadata" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "patches": [ { "op": "add", "path": "/new-field", "value": "new-value" }, { "op": "replace", "path": "/owner", "value": "new-owner" }, { "op": "remove", "path": "/old-field" } ] }'
Key Filtering Examples The KMS API supports powerful filtering capabilities. Here are some common examples:
Filter by Engine curl -X GET "https://api.lamassu.io/api/kms/v1/keys?filter=engine_id[eq]aws-kms-prod" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Filter by Algorithm curl -X GET "https://api.lamassu.io/api/kms/v1/keys?filter=algorithm[eq]RSA" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
curl -X GET "https://api.lamassu.io/api/kms/v1/keys?filter=tags[contains]production" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
curl -X GET "https://api.lamassu.io/api/kms/v1/keys?filter=metadata.owner[eq]security-team" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Complex Filters # Keys with RSA algorithm AND production tag curl -X GET "https://api.lamassu.io/api/kms/v1/keys?filter=algorithm[eq]RSA;tags[contains]production" \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
