Skip to main content
POST
/
v1
/
security
/
keys
Create Key
curl --request POST \
  --url https://api.example.com/v1/security/keys \
  --header 'Content-Type: application/json' \
  --data '{
  "request": {}
}'
{
  "key_id": {},
  "error": "<string>"
}
Creates a new encryption key and returns its unique identifier. The key is generated using secure random material (32 bytes from OS RNG) and is immediately marked as active for encryption operations.

​
Request

This endpoint accepts an empty JSON object.
​
request
object
Empty object {}

​
Response

​
key_id
string (uuid)
required
Unique identifier for the newly created key. Use this ID for encryption and rotation operations.

​
Example

Create a new encryption key
curl -X POST http://localhost:8080/v1/security/keys \
  -H 'Content-Type: application/json' \
  -d '{}'
Response
{
  "key_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Error Responses

​
error
string
Error message describing what went wrong
Status CodeDescription
200Key created successfully
500Internal server error (storage backend failure)
Key material is generated using OsRng and wrapped with zeroize::Zeroizing to prevent memory leaks. The actual key bytes are never logged or exposed through the API.

​
Key Properties

  • Material: 32 bytes of cryptographically secure random data
  • Algorithm: AES-256-GCM (default)
  • Status: Marked as active: true on creation
  • Lineage: A new lineage ID is created for tracking rotation history
  • Version: Initial version is 1

​
Next Steps

  • Use the returned key_id to encrypt data
  • Rotate the key when needed for security best practices
  • Store the key_id securely in your application configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us