---
title: "Amplia quick reference"
description: "Amplia on one page: what it is for, client packages, API key and endpoint, the order and issuance calls, errors and test setup."
canonical: "https://docs.lacunasoftware.com/en-us/articles/amplia/quick-reference"
locale: "en"
product: "Amplia"
last_updated: "2026-10-12"
---

# Amplia quick reference

The essentials of Amplia's API on one page, with links to the full pages and samples.

## What it is for

Amplia is a platform for creating and managing certification authorities (CAs) or entire public key infrastructures (PKIs), used as Lacuna's cloud service (SaaS) or as your own on-premises instance. Operators manage CAs, templates and orders on a web dashboard, while your systems create certificate orders and issue certificates through its REST API. 

| Choose instead | When it fits better |
|---|---|
| [Amplia Reg](https://docs.lacunasoftware.com/en-us/articles/amplia-reg) | Registration agents must validate and approve the holder's identity before issuance. Amplia Reg is the Registration Authority (RA): your application creates the order through Amplia Reg's own API, and Amplia only issues the certificate at the end. |
| [Lacuna PSC](https://docs.lacunasoftware.com/en-us/articles/psc) | You need to store and manage cloud certificates behind a DOC-ICP-17.01 (OAuth 2.0) interface. PSC is a companion system that relies on Amplia. |
| [GrantID](https://docs.lacunasoftware.com/en-us/articles/grant-id) | You need sign-in, single sign-on or multiple authentication factors for your apps, not certificates. Amplia itself uses GrantID to sign users in. |
| [PKI SDK](https://docs.lacunasoftware.com/en-us/articles/pki-sdk/quick-reference) | You only need to decode and validate certificates (or decode, validate and issue attribute certificates) inside a .NET application, without running a CA. |
| [Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/quick-reference) or [Signer](https://docs.lacunasoftware.com/en-us/articles/signer/quick-reference) | You need to sign documents. Certificates issued by Amplia can be used to sign with them right away. |

## Install

The REST API needs no package: any HTTP client can call it, and its OpenAPI description (API version 5.0.1) is at https://docs.lacunasoftware.com/openapi/amplia.json.  Client libraries:

| Language | Package | Current major | Registry |
|---|---|---|---|
| .NET | `Lacuna.Amplia.Client` | 5 | [NuGet](https://www.nuget.org/packages/Lacuna.Amplia.Client) |
| Java | `com.lacunasoftware.amplia:amplia-client` | 1 | [Maven Central](https://central.sonatype.com/artifact/com.lacunasoftware.amplia/amplia-client) |
| Node.js | `amplia-client` | 1 | [npm](https://www.npmjs.com/package/amplia-client) |
| PHP | `lacuna/amplia-client` | 1 | [Packagist](https://packagist.org/packages/lacuna/amplia-client) |
| Python | `amplia-client` | 1 | [PyPI](https://pypi.org/project/amplia-client/) |

* The .NET client is built from the same source as Amplia: get an `IAmpliaService` from dependency injection (`services.AddAmplia(...)`)
  or from `AmpliaServicesFactory.GetService(endpoint, apiKey)`; the older `AmpliaClient` class is `[Obsolete]`. Unlike the other
  clients, it also sends the issue link by email or SMS and reads its QR code. See [.NET client](https://docs.lacunasoftware.com/en-us/articles/amplia/integration#dotnet-client). 
* The client majors don't follow Amplia's version: every endpoint that the 1.x clients call is served by Amplia 5.0.1. 

## Configuration and authentication

* **API key**: every request sends your application's API key in the `X-Api-Key` header, in the form `yourapp|xxxx…`. 
  To get one, sign in to the Amplia dashboard, create an application under **Applications**, mark its role, then add a key under **Keys** and copy it, since it cannot be retrieved later:
  see [Create an application and an API key](https://docs.lacunasoftware.com/en-us/articles/amplia/integration#api-key). 
  An application that runs the whole flow needs the **Worker** role. A **Registration Agent** application can create orders, have Amplia email or text the issue link, and revoke, but cannot read the issue link or issue certificates. 
* **Endpoint**: the address of the Amplia instance, prefixed to every relative API URL. 
  Lacuna's cloud instance is `https://amplia.lacunasoftware.com/`, the default endpoint in the samples; with an on-premises instance, use the [dashboard domain](https://docs.lacunasoftware.com/en-us/articles/amplia/on-premises#dashboard-domain) you chose. 
  TODO(docs): no separate sandbox or test endpoint is documented.
* **Language**: the API observes the `Accept-Language` header (`en-US` or `pt-BR`); error messages are not affected by it. 
* **Webhook**: Amplia can notify your system whenever a certificate is issued; the notification body is a `WebhookEventModel` whose `type` is `OrderCertificateIssued`. 
  An **Admin** or **Manager** sets the URL and the authentication type (the header Amplia sends: `Bearer`, `ApiKey`, a custom `Authorization` or `Basic`) under **Settings** > **Webhook configuration**.
  Amplia posts JSON with PascalCase property names (`Type`, `Order`, `Certificate`) and counts any 2xx answer as delivered; its `Basic` value is not the standard encoding. See [Webhook](https://docs.lacunasoftware.com/en-us/articles/amplia/integration#webhook). 

The Node.js samples keep `caId` (the CA that issues the certificates), `apiKey` and `endpoint` (with a trailing `/`) in `config/default.js`, and create the client from the endpoint and the API key: 

```js
const { AmpliaClient } = require("amplia-client");

class Util {
	static getAmpliaClient() {
		let CONFIG = Config.getInstance().get('amplia');
		let key = CONFIG['apiKey'];
		let endpoint = CONFIG['endpoint'];
		return new AmpliaClient({
			endpoint: endpoint,
			apiKey: key
		});
	}
}
```

## Core operations

Every issuance starts with an order on a CA; then either the holder issues the certificate on their own device, or your server issues it.  The code is Node.js, trimmed from the [PKI Suite samples](https://github.com/LacunaSoftware/PkiSuiteSamples); the blocks after the first use the `order` it creates.

The [integration guide](https://docs.lacunasoftware.com/en-us/articles/amplia/integration) covers each flow in Java, Node.js, PHP and Python, with the REST calls behind them.

### Create a certificate order

An order holds the holder's data, the CA that issues the certificate and its validity. `client.createOrder(request)` posts to `POST /api/orders/{format}`, for example `/api/orders/pki-brazil` for ICP-Brasil parameters.  Guide: [Create certificate orders](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/orders). Full sample: [issue-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js).

```js
const {PkiBrazilCertificateParameters, CreateOrderRequest, CertificateKinds} = require('amplia-client');

const CONFIG = Config.getInstance().get('amplia');
const client = Util.getAmpliaClient();
const request = new CreateOrderRequest({
	caId: CONFIG['caId'],
	validityEnd: Util.getTwoYearsFromNowDate(),
	kind: CertificateKinds.PUBLIC_KEY,
	parameters: new PkiBrazilCertificateParameters({
		name: req.body.subjectName,
		cpf: req.body.cpf
	})
});
let order = await client.createOrder(request);
```

### Let the holder issue on their own machine

`client.getOrderIssueLink(orderId, returnUrl)` (`GET /api/orders/{id}/issue-link?returnUrl=…`) returns a link to Amplia's issue page, where the key pair is generated on the user's machine; Amplia then returns to `returnUrl`. The sample also sets `phoneNumber` in the order parameters, which this flow needs to verify the holder's identity.  Guide: [Issue on the holder's machine](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/issue-on-user-machine). Full sample: [issue-cert-user-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-user-amplia.js).

```js
const RETURN_URL = 'http://localhost:3000/issue-cert-user-amplia/complete';

let link = await client.getOrderIssueLink(order.getId(), RETURN_URL);
res.render('issue-cert-user-amplia/redirect', {
	redirectLink: link
});
```

Amplia can also deliver the link itself. `POST /api/orders/{id}/send-issue-email-request` emails it to the address in the order's parameters, and `POST /api/orders/{id}/send-issue-sms-request` texts it to the order's phone number; since your system never sees the link, a **Registration Agent** application can use them.
`GET /api/orders/{id}/issue-qrcode-image` returns a PNG QR code that leads to the issue page, and `issue-qrcode-data` the URL it holds. Details: [Other ways to deliver the issue link](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/issue-on-user-machine#deliver-the-link). 

### Issue from a CSR made on your server

`client.issueCertificate(orderId, csr, keyMedia)` (`POST /api/v2/certificates`, body `orderId`, `csr`, `keyMedia`) issues the order for a CSR you generated; the sample makes the key and CSR with PKI Express. `keyMedia` is one of `PC`, `CryptoDevice`, `Mobile` or `Cloud`.
 Guide: [Issue from a CSR](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/issue-from-csr). Full sample: [issue-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js).

```js
const {KeyGenerator} = require('pki-express');
const {KeyMedia } = require('amplia-client/lib/enums');

const keyGenerator = new KeyGenerator({
	keySize: req.body.keySize,
	genCsr: true
});
let genKey = await keyGenerator.generate();
let generatedKey = genKey.getKey();
let cert = await client.issueCertificate(order.getId(), genKey.getCsr(), KeyMedia.PC);
let certId = cert.getId();
// WARNING: It is highly RECOMMENDED to ENCRYPT the key before storing
// in your database.
StorageMock.storeSync(generatedKey, certId, '.json');
StorageMock.storeSync(cert.getContentRaw(), certId, '.cer');
```

### Issue a PKCS #12 (.pfx) file

`client.issuePkcs12Certificate(orderId, password, keySize)` (`POST /api/certificates/pkcs12`) has Amplia generate the key and return a password-protected PKCS #12 file.  Guide: [Issue a PKCS #12 file](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/pkcs12). Full sample: [issue-pkcs12-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-pkcs12-cert-server-amplia.js).

```js
let cert = await client.issuePkcs12Certificate(order.getId(), req.body.senha, 2048);
let certId = cert.getModel().id;
StorageMock.storeSync(cert.getPfxContent(), certId, '.pfx');
```

### Issue an attribute certificate

Create the order with `kind` set to `Attribute` and CIE parameters (a Brazilian student ID), on a CA configured for attribute certificates, which is not the CA that issues public-key certificates; then issue it without a CSR, since an attribute certificate has no key pair of its own. The CIE order endpoint is `POST /api/orders/cie`.  Guide: [Attribute certificates](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/attribute-certificates). The only sample is in PHP: [complete.php](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-attribute-amplia/complete.php).

### Revoke a certificate

The Node.js client's `client.revokeCertificate(certificateId)` sends `DELETE /api/certificates/{id}`.  Amplia publishes CRLs on your [access domains](https://docs.lacunasoftware.com/en-us/articles/amplia/on-premises#access-domains) and can answer [OCSP](https://docs.lacunasoftware.com/en-us/articles/amplia/on-premises/configure-ocsp) requests. 
The call takes no revocation reason and can't be undone. Each CA issues CRLs on its own schedule (every `crlIssuePeriod`), so a revocation shows on its next scheduled CRL, with no reason code, while Amplia's OCSP responder reports it right away. Guide: [Revoke certificates](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/revocation). 

**Renewal**: Amplia can renew certificates, giving the holder a new certificate in place of the one that is expiring. 
TODO(docs): no page documents how to renew a certificate through the API.

## Errors

The API answers with an HTTP status code; for API errors, the body is an `ErrorModel` with `code`, `message` and `details`. Error messages do not follow `Accept-Language`: log them rather than show them to users. 

| Status | Meaning |
|---|---|
| 400 Bad Request | Syntax error, for instance a required field is missing |
| 401 Unauthorized | API key not provided or invalid |
| 403 Forbidden | The API key is valid, but the application lacks the permission for the operation |
| 422 Unprocessable Entity | API error; the body is an `ErrorModel` |
| 500 Internal Server Error | Unexpected error; the `exceptionCode` in the body helps Lacuna support |

The Node.js client rejects with `AmpliaError` on a 422 (its message carries the `code`), `RestError` on other HTTP errors and `RestUnreachableError` when the endpoint cannot be reached. Its `AmpliaErrorCodes` enum names codes such as `OrderNotFound`, `OrderAlreadyFulfilled` and `CertificateAlreadyRevoked`. 
The .NET client throws `AmpliaException`, whose `Code` is the error code. 

[Error codes](https://docs.lacunasoftware.com/en-us/articles/amplia/integration/errors#error-codes) lists the codes that the issuance calls return and what each means. A permission the application lacks gets 403 Forbidden, not an error code. 

## Test certificates and credentials

* [Test certificates](https://docs.lacunasoftware.com/en-us/articles/pki-guide/test-certs): PKCS #12 files from the Lacuna Test PKI, with password `1234`, for development and staging only. 
* The Node.js sample's `config/default.js` ships with a trial API key for Lacuna's cloud instance, which expires on 2026-10-31, and the id of a sample CA;
  the Node.js and PHP configuration templates ask for your own key and CA id instead. 
* When the samples stop working, for instance once their key expires, the sample configuration says to contact Lacuna support at suporte@lacunasoftware.com. 

## Try it

Issue test certificates on the demo site, or run the samples in Java, Node.js, PHP and Python:

**Demos and samples**

- Live demo: [Issue an e-CNPJ certificate](https://try.lacunasoftware.com/en/amplia/issue-e-cnpj-certificate)
- Live demo: [Issue an e-CPF certificate](https://try.lacunasoftware.com/en/amplia/issue-e-cpf-certificate)
- Live demo: [Issue an e-CPF with your face](https://try.lacunasoftware.com/en/amplia/issue-an-ecpf-with-your-face)
- Live demo: [Issue an SSL/TLS certificate](https://try.lacunasoftware.com/en/amplia/issue-ssl-tls-certificate)
- Issue a certificate with the key on the user's machine using Amplia: [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/IssueCertUserAmpliaController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-user-amplia.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-user-amplia/index.php) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/issue_cert_user_amplia.py)
- Issue a certificate with the key on the server using Amplia: [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/IssueCertServerAmpliaController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-server-amplia/index.php) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/issue_cert_server_amplia.py)
- Issue a PKCS #12 certificate using Amplia: [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-pkcs12-cert-server-amplia.js)
- Issue an attribute certificate using Amplia: [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-attribute-amplia/index.php)