Skip to main content
POST
/
v1
/
security
/
encrypt
Encrypt Data
curl --request POST \
  --url https://api.example.com/v1/security/encrypt \
  --header 'Content-Type: application/json' \
  --data '
{
  "key_id": {},
  "input": "<string>"
}
'
{
  "envelope": "<string>",
  "error": "<string>"
}
Encrypts plaintext data using the specified encryption key and returns a base64-encoded envelope containing the ciphertext and metadata.

​
Request

​
key_id
string (uuid)
required
The unique identifier of the encryption key to use. Key must be active.
​
input
string
required
The plaintext string to encrypt. Will be converted to UTF-8 bytes before encryption.

​
Response

​
envelope
string
Base64-encoded binary envelope containing the encrypted data and metadata. This envelope is self-describing and includes:
  • Version (u8): Envelope format version (currently 1)
  • Algorithm (u8): Encryption algorithm identifier
  • Key ID (Uuid): Reference to the encryption key
  • Nonce (bytes): Random nonce for AES-256-GCM
  • Ciphertext (bytes): Encrypted payload
  • Tag (bytes): Authentication tag for integrity verification

​
Example

Encrypt sensitive data
KEY_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST http://localhost:8080/v1/security/encrypt \
  -H 'Content-Type: application/json' \
  -d "{
    \"key_id\": \"${KEY_ID}\",
    \"input\": \"hello world\"
  }"
Response
{
  "envelope": "AQEgVQ6EAOKbQdSnFkRmVUQAAAwAAABhYmNkZWZnaGlqa2wQAAAA8j+9X..."
}

​
Envelope Format

The envelope is a deterministic binary format that can be safely stored or transmitted. It includes all information needed for decryption:
  1. Version byte: Format compatibility (must be 1)
  2. Algorithm byte: Crypto algorithm used
  3. Key ID: 16 bytes (UUID)
  4. Nonce length + nonce: Variable length (12 bytes for AES-256-GCM)
  5. Ciphertext length + ciphertext: Variable length
  6. Tag length + tag: Variable length (16 bytes for AES-256-GCM)
The envelope is then base64-encoded for safe transport in JSON.

​
Error Responses

​
error
string
Error message describing what went wrong
Status CodeError TypeDescription
200-Encryption successful
404KeyNotFoundThe specified key_id does not exist
400KeyInactiveThe key exists but is inactive (use active key or rotate)
400SerializationFailed to serialize the envelope
500EncryptionCryptographic operation failed

​
Example Error

404 Not Found
{
  "error": "key not found: 550e8400-e29b-41d4-a716-446655440000"
}
400 Bad Request
{
  "error": "key is inactive: 550e8400-e29b-41d4-a716-446655440000"
}
Only active keys can be used for encryption. If you receive a KeyInactive error, you must rotate the key or use a different active key. This design ensures that rotated keys cannot be used for new encryption operations.

​
Algorithm Details

The platform uses AES-256-GCM as the default encryption algorithm:
  • Mode: Galois/Counter Mode (AEAD)
  • Key size: 256 bits (32 bytes)
  • Nonce size: 96 bits (12 bytes)
  • Tag size: 128 bits (16 bytes)
  • Properties: Authenticated encryption with associated data

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us