What are Encryption Keys?

Encryption keys are asymmetric key pairs used to encrypt sensitive data before sending it to the Hyperion API. You encrypt monitorable and event data with the public key and only the Hyperion API can decrypt it with the corresponding private key.

Encryption keys enable:

• Data protection at rest: Sensitive PII is encrypted before reaching the API
• Defense in depth: Additional encryption layer beyond HTTPS transport security
• Regulatory compliance: Meet requirements for end-to-end encryption of sensitive data
• Key rotation: Manage key lifecycles with configurable effective and expiration dates

Encryption Key Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "algorithm": "RSA-OAEP-256",
  "effectiveAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2026-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Encryption Key Fields

Field	Description
id	Unique identifier assigned by Hyperion (used as kid in JWE headers)
partnerId	ID of the partner organization that owns the key
publicKey	Public key (PEM string for RSA keys, JWK object for HPKE keys)
algorithm	JWE algorithm identifier (e.g., RSA-OAEP-256, HPKE-0)
effectiveAt	Date and time when the key becomes active
expiresAt	Date and time when the key expires
createdAt	Timestamp when the key was created

Creating an Encryption Key

Create a new encryption key by sending a POST request with the desired algorithm:

cURLPOST

Hyperion generates the key pair and returns the encryption key metadata including the publicKey for encrypting data.

Key Rotation

Encryption keys support rotation through effectiveAt and expiresAt dates, allowing you to transition between keys seamlessly.

How Rotation Works

1. Create a new key before the current key expires. The new key can have an effectiveAt date in the future.
2. Use the latest key for encryption: Always fetch the latest non-expired key when encrypting new data.
3. Old keys remain valid for decryption: The Hyperion API retains old keys so it can still decrypt data that was encrypted with them.
4. Old key expires: Once the old key's expiresAt date passes, it can no longer be used for new encryption but previously encrypted data remains accessible.

Date Constraints

• expiresAt must be at least 30 days after effectiveAt
• expiresAt must be at most 2 years after effectiveAt
• If effectiveAt is not provided, it defaults to the current time
• If expiresAt is not provided, it defaults to 2 years after the effective date

Set up monitoring for key expiration dates. If all encryption keys expire, you will not be able to encrypt data until a new key is created.

JWKS Endpoint

Your active encryption keys are available in JSON Web Key Set (JWKS) format at the partner JWKS endpoint:

cURLGET

The JWKS response contains all of your active (non-expired) encryption keys, plus the Hyperion webhook signing public key (use: "sig"). Partners that already fetch this endpoint can verify webhook signatures from it without calling the global JWKS. When encrypting data, use the kid from the encryption key to find the correct public key in the JWKS response.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM...",
      "e": "AQAB",
      "kid": "550e8400-e29b-41d4-a716-446655440000",
      "use": "enc",
      "alg": "RSA-OAEP-256",
      "key_ops": ["encrypt"]
    }
  ]
}

JWKS Fields

Field	Description
kty	Key type (RSA for RSA keys, EC for HPKE P-256/P-384/P-521, OKP for HPKE X25519/X448, AKP for X-Wing)
kid	Key identifier matching the encryption key id
use	Key usage (enc for encryption keys, sig for the Hyperion webhook signing key)
alg	Algorithm identifier (e.g., RSA-OAEP-256, HPKE-0, ES256)
key_ops	Array of permitted operations (["encrypt"] for encryption keys)

Cache JWKS responses to reduce latency. If a kid is not found in your cache, refresh the JWKS to pick up newly created keys.

Supported Algorithms

The Hyperion API supports two families of encryption algorithms:

RSA

RSA-based algorithms use asymmetric RSA keys for key encryption combined with AES-GCM for content encryption.

Algorithm	Key Encryption	Content Encryption	Minimum Key Size
RSA-OAEP-256	RSA-OAEP with SHA-256	AES-256-GCM	2048-bit
RSA-OAEP-512	RSA-OAEP with SHA-512	AES-256-GCM	4096-bit

RSA keys are provided in PEM format.

HPKE

HPKE (Hybrid Public Key Encryption) algorithms use elliptic-curve or post-quantum key types. Keys are provided in JWK format.

Algorithm	KEM	Key Type
HPKE-0	DHKEM(P-256, HKDF-SHA256)	EC P-256
HPKE-1	DHKEM(P-384, HKDF-SHA384)	EC P-384
HPKE-2	DHKEM(P-521, HKDF-SHA512)	EC P-521
HPKE-3	DHKEM(X25519, HKDF-SHA256)	OKP X25519
HPKE-4	DHKEM(X25519, HKDF-SHA256)	OKP X25519
HPKE-5	DHKEM(X448, HKDF-SHA512)	OKP X448
HPKE-6	DHKEM(X448, HKDF-SHA512)	OKP X448
HPKE-7	DHKEM(P-256, HKDF-SHA256)	EC P-256
HPKE-9	MLKEM768-X25519 (X-Wing)	AKP X-Wing
HPKE-XWING-SHA256-AES256GCM	MLKEM768-X25519 (X-Wing)	AKP X-Wing

HPKE keys can also be used with Key Encapsulation variants (HPKE-0-KE through HPKE-9-KE), which combine HPKE key management with AES-256-GCM content encryption.

The last two algorithms are post-quantum. Both use the X-Wing hybrid KEM, which combines ML-KEM-768 with X25519. Post-quantum keys use the AKP key type from RFC 9964.

Related Resources

API Reference

• Create Encryption Key - Generate a new encryption key
• Get Encryption Key - Retrieve encryption key details
• Get Latest Key - Retrieve the most recent non-expired key
• List Encryption Keys - List all encryption keys
• Update Encryption Key - Modify encryption key configuration

Related Concepts

• Monitorables - Entities whose data can be encrypted