Skip to main content

What are Encryption Keys?

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

Encryption keys enable:

  • Data protection: Sensitive payloads stay encrypted beyond HTTPS transport security
  • Key rotation: Manage key lifecycles with configurable effective, inactive, and expiration dates
  • Algorithm choice: Select RSA or HPKE algorithms that fit your client libraries and security requirements

Encryption Key Structure​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "algorithm": "HPKE-XWING-SHA256-AES256GCM",
  "publicKey": "MIIE1DANBgsrBgEEAYPmLYHIegOCBMEA...",
  "signature": "dGVzdC1zaWduYXR1cmU",
  "certificateChain": ["MIIB..."],
  "effectiveAt": "2024-01-15T10:30:00.000Z",
  "inactiveAt": "2024-04-12T10:30:00.000Z",
  "expiresAt": "2024-04-15T10:30:00.000Z",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Encryption Key Fields​

FieldDescription
idUnique identifier assigned by Hyperion (used as kid in JWKS)
partnerIdID of the partner organization that owns the key
algorithmEncryption algorithm identifier
publicKeyPublic key as Base64-encoded SPKI DER
signatureBase64URL ECDSA signature over the key bundle
certificateChainX.509 certificate chain used to verify signature (leaf at index 0)
effectiveAtDate and time when the key becomes active
inactiveAtDate and time when you should fetch the next key (computed by Hyperion)
expiresAtDate and time when the key expires
createdAtTimestamp when the key was created

Choosing an Algorithm​

FamilyAlgorithmsWhen to use
X-WingHPKE-XWING-SHA256-AES256GCM, HPKE-9Post-quantum hybrid protection for new integrations
HPKEHPKE-0 through HPKE-7Standard elliptic-curve HPKE when your libraries already support those suites
RSARSA-OAEP-256, RSA-OAEP-512Broadest library support for JWE-style encryption

See Supported Algorithms for the full list.

Creating an Encryption Key​

Create a new encryption key by sending a POST request. When no rotation config is set, algorithm is required. Defaults: effectiveAt is now; expiresAt is 90 days later (or your configured rotation schedule).

cURLPOST

Hyperion generates the key pair and returns the encryption key metadata, including the signed key bundle.

Key Lifetime​

  • expiresAt must be at least 7 days after effectiveAt
  • expiresAt must be at most 2 years after effectiveAt
  • rotationSchedule must be between 7 days and 2 years

When you deactivate a compromised key, the 7-day minimum does not apply. The 2-year maximum always applies.

Verifying the Key Bundle Signature​

  1. Take the leaf certificate from certificateChain[0] and import its public key.
  2. Rebuild the signed bundle: length-prefixed SPKI public key bytes, key id, effectiveAt, inactiveAt, and expiresAt (each as UTF-8 ISO 8601 strings).
  3. Hash the bundle with SHA-256 and verify the Base64URL-decoded signature as ECDSA P-256 with IEEE P1363 encoding.

Current Key​

Fetch the currently effective, non-expired key:

cURLGET

Prefer this endpoint when encrypting new data. Keys remain available for decryption until expiresAt.

Key Lifecycle​

TimestampMeaning
effectiveAtKey may be used for encryption and appears as current when not expired
inactiveAtFetch the next key from /encryption-keys/current or JWKS. Hyperion computes this as three days before expiresAt
expiresAtKey can no longer be used for new encryption

You cannot set inactiveAt yourself. When automatic rotation is configured, the next key becomes effective at the current key's inactiveAt, so the two keys overlap until the current key expires.

Old keys remain available so Hyperion can decrypt data that was encrypted with them until they expire.

Deactivating a Compromised Key​

If a key may be compromised, update it immediately and set expiresAt to now. Hyperion recomputes inactiveAt and re-signs the key bundle. The key stops being returned from /encryption-keys/current and from partner JWKS.

cURLPUT

Create a replacement key before or right after deactivation so you can keep encrypting new data.

Automatic Rotation Config​

Set a rotation schedule so Hyperion can create the next key for you:

cURLPOST

rotationSchedule is an ISO 8601 duration. Hyperion checks daily and creates a new key when the newest key's next rotation falls within the next day. The next rotation is the newest key's inactiveAt, or effectiveAt plus the schedule if that comes first. The new key becomes effective at that time, before the previous key expires.

Ad-hoc Keys Reset the Schedule​

If you create a key yourself while a schedule is configured, the next automatic rotation is measured from that key.

Example with a P7D schedule:

  1. Automatic rotation would have created a key in two days.
  2. You create an ad-hoc key today. It expires in seven days, and its inactiveAt is four days from today.
  3. The next automatic key becomes effective four days from today and overlaps the ad-hoc key for three days.

Delete the config with DELETE /v1/encryption-keys/config when you want to manage rotation yourself.

If all encryption keys expire and no rotation config is set, you will not be able to encrypt data until a new key is created.

JWKS Endpoint​

The current encryption key is available in JSON Web Key Set (JWKS) format at the partner JWKS endpoint:

cURLGET

The response contains the current encryption key (use: "enc") with nbf and exp, plus the Hyperion webhook signing public key (use: "sig").

{
  "keys": [
    {
      "kty": "AKP",
      "kid": "550e8400-e29b-41d4-a716-446655440000",
      "use": "enc",
      "alg": "HPKE-XWING-SHA256-AES256GCM",
      "key_ops": ["encrypt"],
      "pub": "base64url-public-key...",
      "nbf": 1710000000,
      "exp": 1717776000
    },
    {
      "kty": "EC",
      "kid": "signing-key-id",
      "use": "sig",
      "alg": "ES256",
      "crv": "P-256",
      "x": "base64url...",
      "y": "base64url...",
      "x5c": ["MIIB..."]
    }
  ]
}

JWKS Fields​

FieldDescription
ktyKey type (RSA for RSA keys, EC for HPKE P-256/P-384/P-521, OKP for HPKE X25519/X448, AKP for X-Wing)
kidKey identifier matching the encryption key id
useKey usage (enc for encryption keys, sig for the Hyperion webhook signing key)
algAlgorithm identifier (e.g., RSA-OAEP-256, HPKE-0, ES256)
n/eRSA modulus and exponent (RSA keys)
crv/x/yCurve and coordinates (EC and OKP keys)
pubRaw public key bytes (AKP keys)
nbf/expValidity window for the encryption key as Unix timestamps
key_opsArray 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. For every algorithm, publicKey is returned as Base64-encoded SPKI DER, and the JWKS endpoint returns the same key as a JWK.

RSA​

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

AlgorithmKey EncryptionContent EncryptionKey Size
RSA-OAEP-256RSA-OAEP with SHA-256AES-256-GCM2048-bit
RSA-OAEP-512RSA-OAEP with SHA-512AES-256-GCM4096-bit

RSA keys are provided in PEM format.

HPKE​

HPKE (Hybrid Public Key Encryption) algorithms use elliptic-curve or post-quantum key types.

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

HPKE keys can also be used with Key Encapsulation variants (HPKE-0-KE through HPKE-9-KE, and HPKE-XWING-SHA256-AES256GCM-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.

API Reference​