Skip to main content

Device-self key retrieval

How device agents retrieve certificate private keys and what to expect for each policy.

Overview​

Device agents authenticate with a short-lived JWT and request the bundle for a specific certificate.

Behavior by policy​

  • HYBRID
    • Returns an AEAD-encrypted bundle when the device wrap is available.
    • If the data key is not yet wrapped for the device, returns 409 DEVICES::WRAP_PENDING.
  • DEVICE_REQUIRED
    • Same as HYBRID but server-side plaintext exports are forbidden.
  • MASTER_ONLY
    • If server_decrypt_export is enabled, plaintext may be returned directly.
    • If the certificate has not been issued yet, you receive 409 CERTS::NOT_ISSUED.

Headers and download​

For plaintext responses, the service may include:

  • Content-Disposition: attachment; filename="cert-<id>.pem" (or a zip when applicable)
  • Vary: Origin and CORS headers when accessed from browsers
  • Respect 409 codes with exponential backoff.
  • Handle language-specific error messages but key off the numeric code for logic.
  • Cache short-lived results only in memory; never persist plaintext materials.