> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formepdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials & Certificates

> Manage X.509 certificates for digital certification — upload, store securely, and reference by ID in API calls.

The Credentials page in the dashboard lets you upload and manage X.509 certificates for [digital certification](/concepts/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:

```json theme={null}
{
  "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

| Plan     | Certificates |
| -------- | ------------ |
| Free     | 1            |
| Pro      | 5            |
| Team     | Unlimited    |
| Business | Unlimited    |

***

## Using in API Calls

Pass `certificateId` instead of inline PEM fields:

```bash theme={null}
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](/api-reference/certify) for the full endpoint reference.

***

## Generating a Test Certificate

For development and testing, generate a self-signed X.509 certificate with OpenSSL:

```bash theme={null}
# 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.

<Note>
  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`
</Note>

<Tip>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.</Tip>

***

## 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.

***

<Note>Stored certificates are a hosted API feature. Self-hosted users should pass `certificatePem` and `privateKeyPem` directly in API calls.</Note>