Skip to main content

Encryption and key management

Your integration deals with four kinds of key material. Each one has a different owner, lifetime, and failure mode if it's handled badly.

This page covers the keys you hold or generate. Our internal key management — hardware security modules, key-encrypting keys, and rotation schedules for data at rest — is covered in the security questionnaire provided under NDA. Those details can change, so we'd rather keep the current answers there than let stale information live in the docs.

Keys​

KeyWho generates itLifetimeRotation
OAuth client key pairYouUntil you remove itUp to three registered at once
Webhook signing secretUsUntil retiredTwo active, both signatures sent

Every rotation uses an overlap period. You don't need a flag day or any downtime. If your rotation runbook requires both sides to coordinate at an exact moment, you're probably making the process more complicated than it needs to be.

Credentials​

OAuth client keys​

You generate the key pair. The public key is registered against a client in Cockpit as a JWK Set. The private key stays with you and never reaches us.

There's nothing to copy out of Cockpit later and nothing we can recover for you — we never had the private key in the first place.

Rotation is done with an overlap: a client can have up to three public keys registered at the same time. Add the new key first, switch over to it, then remove the old one. See rotating a key for the procedure.

Revocation is immediate. Revoke the client and its tokens are refused on the next request with 401 invalid_access_token. See revoking a client.

A few practical rules, roughly in the order people tend to get them wrong:

  1. Never put private keys in client-side code. A leaked private key can issue cards. Don't put one in a mobile binary, browser bundle, or repository.
  2. Use one client per deployment target. Give each client a useful label. If one is compromised, you should be able to revoke it without taking down every service you run.
  3. Keep keys in a secrets manager or environment variable. Don't check them into a config file.
  4. Set your own rotation schedule. Keys don't expire automatically. Every 90 days is a reasonable default, and there's no downside to rotating them.

See authentication.

Webhook signing secret​

The webhook signing secret is symmetric and uses HMAC-SHA256. It's how you verify that a webhook actually came from us rather than someone who happened to find your endpoint.

Rotation is where the implementation detail matters. During a rotation, the header contains more than one signature:

Aleta-Signature: t=1785508332,v1=5257a869…,v1=9b41f2c0…

While the old and new secrets overlap, we sign each delivery with both and include two v1 values. Your verifier should accept the delivery if any valid v1 signature matches.

Handle multiple v1 values from the start. That way rotation doesn't require a code change. See signature verification.

Transport​

Use TLS 1.2 or newer on every endpoint. TLS 1.3 is preferred.

Plain HTTP is refused rather than redirected. A redirect doesn't help if the credential has already been sent over an unencrypted connection.

Webhook endpoints must also present a certificate that validates against a public root. Self-signed certificates are rejected when the endpoint is configured, rather than letting the problem show up later as failed deliveries.

Suspected compromise​

If you think a credential has leaked:

  1. Revoke it first. Revocation is immediate and doesn't require us. Do this before starting the investigation.
  2. Work out what was exposed. Find out which service had the credential, what it could access, and what might have been done with it.
  3. Tell us. Email it@aletaplanet.com with the client label and whatever you know. See responsible disclosure.

The order matters. There's not much value in investigating a leaked credential while it's still valid.

Last updated on