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	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	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	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	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 or Signer	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
Java	com.lacunasoftware.amplia:amplia-client	1	Maven Central
Node.js	amplia-client	1	npm
PHP	lacuna/amplia-client	1	Packagist
Python	amplia-client	1	PyPI

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

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:

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; the blocks after the first use the order it creates.

The integration guide 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. Full sample: issue-cert-server-amplia.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. Full sample: issue-cert-user-amplia.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.

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. Full sample: issue-cert-server-amplia.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. Full sample: issue-pkcs12-cert-server-amplia.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. The only sample is in PHP: 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 and can answer 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.

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 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: 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
• Live demo: Issue an e-CPF certificate
• Live demo: Issue an e-CPF with your face
• Live demo: Issue an SSL/TLS certificate
• Issue a certificate with the key on the user's machine using Amplia: Java · Node.js · PHP · Python
• Issue a certificate with the key on the server using Amplia: Java · Node.js · PHP · Python
• Issue a PKCS #12 certificate using Amplia: Node.js
• Issue an attribute certificate using Amplia: PHP