Security

API Key Security

API keys are the primary way to authenticate with the Apertur API. Keeping them secure is critical to protecting your account and your users' data.

TOTP for API Keys

For an extra layer of security, you can require a time-based one-time password (TOTP) with every API request that uses a specific key.

1. Open your API key settings and click Enable TOTP.
2. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.).
3. Enter the 6-digit code to verify setup.
4. From now on, include the TOTP code in the X-APTR-TOTP header with every request.

The header name is X-APTR-TOTP. Codes are valid for 30 seconds with a tolerance of one time step.

curl -X POST https://api.apertur.ca/v1/sessions \
  -H "Authorization: Bearer aptr_live_xxxx" \
  -H "X-APTR-TOTP: 123456" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_mode": "webhook", "webhook_url": "https://..." }'

Client Certificates (mTLS)

Mutual TLS (mTLS) provides the highest level of API authentication by requiring a client certificate with every request, in addition to your API key.

1. Generate a client certificate and private key (or use one issued by your organisation's CA).
2. Upload the certificate to your API key settings under Client Certificates.
3. Apertur will validate the certificate on every request.
4. Include both the certificate and key when making API calls (see example below).
5. Requests without a valid client certificate will be rejected with a 403 error.

# cURL with client certificate
curl -X POST https://api.apertur.ca/v1/sessions \
  --cert client.crt \
  --key client.key \
  -H "Authorization: Bearer aptr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_mode": "webhook", "webhook_url": "https://..." }'

Session Passwords

You can protect individual upload sessions with a password. When set, end-users must enter the password before they can upload photos.

curl -X POST https://api.apertur.ca/v1/sessions \
  -H "Authorization: Bearer aptr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_mode": "webhook",
    "webhook_url": "https://your-app.com/webhook",
    "password": "claim-4521-pin"
  }'

Passwords are hashed using bcrypt on the server. Apertur never stores passwords in plaintext and they cannot be retrieved after creation.

SDK Origin Validation

When using the aptr-connect SDK, you can restrict which domains are allowed to use your public key by configuring allowed domains on your OAuth app. The server validates the Origin header of incoming requests against your allowed domains list.

Wildcards are supported: *.example.com matches any subdomain at any depth. Leave the list empty during development to allow all origins.

Configure allowed domains in your partner OAuth app settings.

Webhook Signature Verification

Every webhook delivery includes an X-APTR-Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature to ensure the payload was sent by Apertur and hasn't been tampered with.

const crypto = require("crypto");

function verifyWebhook(body, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(body)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// In your Express handler:
app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  if (!verifyWebhook(req.body, req.headers["x-aptr-signature"], WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  // Safe to process...
  res.status(200).end();
});

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Account Security

Beyond API key security, protect your Apertur account itself with these measures.