Skip to main content
The Credentials page in the dashboard lets you upload and manage X.509 certificates for digital certification. Once uploaded, you can reference certificates by ID in API calls instead of passing raw PEM data.

​
Why Store Certificates?

Without stored credentials, every certification request must include the full certificate PEM and private key PEM in the request body. This means:
  • Private keys travel over the network on every request
  • Keys must be available in every system that calls the API
  • Key rotation requires updating every integration point
With stored credentials: 
{
  "pdf": "<base64>",
  "certificateId": "clxyz...",
  "reason": "Approved"
}
The private key stays encrypted at rest in Forme’s database. Only the certificate ID is needed.

​
Uploading a Certificate

In the dashboard, navigate to Credentials and click Add Certificate. You’ll need:
  1. An X.509 certificate in PEM format (the file starting with -----BEGIN CERTIFICATE-----)
  2. The corresponding RSA private key in PEM format (starting with -----BEGIN PRIVATE KEY-----)
  3. A name for the certificate (e.g., “Production Signing Cert”)

​
Security

  • Encryption at rest: Private keys are encrypted with AES-256-GCM before storage. The encryption key is set via the CERTIFICATE_ENCRYPTION_KEY environment variable.
  • Private key never returned: After upload, the private key is never included in API responses. Only the certificate PEM (public) is accessible.
  • Deletion: Deleting a credential permanently removes both the certificate and encrypted private key.

​
Plan Limits

PlanCertificates
Free1
Pro5
TeamUnlimited
BusinessUnlimited

​
Using in API Calls

Pass certificateId instead of inline PEM fields: 
curl -X POST https://api.formepdf.com/v1/certify \
  -H "Authorization: Bearer forme_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d "{
    \"pdf\": \"$(base64 -w0 contract.pdf)\",
    \"certificateId\": \"clxyz...\",
    \"reason\": \"Approved\"
  }" \
  --output certified.pdf
See Certify API for the full endpoint reference.

​
Generating a Test Certificate

For development and testing, generate a self-signed X.509 certificate with OpenSSL: 
# Generate a private key
openssl genrsa -out key.pem 2048

# Generate a self-signed certificate (valid for 365 days)
openssl req -new -x509 -key key.pem -out cert.pem -days 365 \
  -subj "/CN=Test Signer/O=Acme Corp/C=US"
This creates key.pem (private key) and cert.pem (certificate) in the current directory.
The Forme engine accepts both PKCS#8 and PKCS#1 private key formats. Keys generated with openssl genrsa (PKCS#1) are auto-converted. To explicitly convert to PKCS#8: openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in key.pem -out key-pkcs8.pem
Self-signed certificates work for testing and internal use. For production documents that need third-party trust verification, use a certificate from a trusted Certificate Authority (CA) or your organization’s PKI.

​
Getting a Production Certificate

For documents that need to be trusted by external recipients:
  1. Certificate Authority (CA): Purchase a document signing certificate from a CA like DigiCert, GlobalSign, or Sectigo. These are trusted by Adobe Acrobat and other PDF viewers.
  2. Organizational PKI: If your organization runs its own PKI, issue a certificate from your internal CA.
  3. Government PKI: Some jurisdictions require certificates from government-approved CAs for legal documents.
Stored certificates are a hosted API feature. Self-hosted users should pass certificatePem and privateKeyPem directly in API calls.