Integration guide - Amplia

Your system can create certificate orders and issue certificates through Amplia's REST API, while operators manage CAs, templates and orders on the dashboard. This guide covers the API calls; for a one-page summary, see the Amplia quick reference.

Before you start

You need three values:

• API key: every request sends your application's API key in the X-Api-Key header, in the form yourapp|xxxx…. To get one, create an application and an API key on the Amplia dashboard.
• Endpoint: the address of the Amplia instance, prefixed to every relative URL of the API. Lacuna's cloud instance is https://amplia.lacunasoftware.com/, the default in the samples; with an on-premises instance, use the dashboard domain you chose. TODO(docs): no separate sandbox or test endpoint is documented.
• CA id: the id of the CA that issues the certificates, sent as caId when you create an order. The samples keep it in their configuration next to the API key; the attribute certificate sample uses a second CA, since attribute certificates need a CA set up for them. The samples' comments add that an application can have a default CA, in which case caId can be left out. TODO(docs): where a default CA is set for an application.

The API observes the Accept-Language header (en-US or pt-BR), which also sets the language of the issue links it returns; error messages are not affected by it.

Create an application and an API key

Your system calls the API as an application of an Amplia subscription, with a role that decides what it can do:

1. Sign in to the Amplia dashboard and click Applications on the left menu, then Add.
2. Fill out a name, select the subscription on which the certificates are issued and mark the application's role (see below), then click Create.
3. Click Keys, then Add. Fill out a description and an expiration, then click Create.
4. Copy the API key: it cannot be retrieved later.

Role	Create orders, have Amplia email or text the issue link, revoke	Get the issue link or QR code, issue certificates	Webhook settings
Worker	Yes	Yes	No
Registration Agent	Yes	No	No
Manager, Admin	Yes	Yes	Yes

A system that runs the whole flow needs Worker, the role that Amplia Reg also uses. A Registration Agent application can create orders and send the holder the issue link by email or SMS, but cannot read the link or issue the certificate itself.

Client libraries

Any HTTP client can call the API, whose OpenAPI description is at https://docs.lacunasoftware.com/openapi/amplia.json. Lacuna publishes client libraries, which the samples use:

Language	Package	Registry
.NET	Lacuna.Amplia.Client	NuGet
Java	com.lacunasoftware.amplia:amplia-client	Maven Central
Node.js	amplia-client	npm
PHP	lacuna/amplia-client	Packagist
Python	amplia-client	PyPI

The client majors don't follow Amplia's version: every endpoint that the 1.x clients below call is served by Amplia 5.0.1. The .NET client is described below.

The Java (1.2.1), Node.js (1.3.3), PHP (1.3.0) and Python (1.0.0) clients wrap these calls:

Operation	Node.js, Java, PHP	Python	Endpoint
Create an order	createOrder	create_order	POST /api/orders/{format}
Get an order	getOrder	get_order	GET /api/v2/orders/{id} (Java: GET /api/orders/{format}/{id})
Get the issue link	getOrderIssueLink	get_order_issue_link	GET /api/orders/{id}/issue-link
Issue from a CSR	issueCertificate	issue_certificate	POST /api/v2/certificates
Issue a PKCS #12 file	issuePkcs12Certificate (Node.js only)		POST /api/certificates/pkcs12
Revoke a certificate	revokeCertificate	revoke_certificate	DELETE /api/certificates/{id}

None of the four sends the issue link by email or SMS or reads its QR code: call those endpoints directly, or use the .NET client (see Other ways to deliver the issue link).

Each sample creates the client from the endpoint and the API key:

Node.js

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

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

Java

import com.lacunasoftware.amplia.AmpliaClient;

public static AmpliaClient getAmpliaClient() {
	String apiKey = getProperties().getAmplia().getApiKey();
	String endpoint = getProperties().getAmplia().getEndpoint();
	if (endpoint == null || endpoint.length() == 0) {
		endpoint = "https://amplia.lacunasoftware.com/";
	}
	return new AmpliaClient(endpoint, apiKey);
}

PHP

use Lacuna\Amplia\AmpliaClient;

public static function getAmpliaClient()
{
    $config = getConfig();
    $ampliaApiKey = $config['amplia']['apiKey'];
    $ampliaEndpoint = $config['amplia']['endpoint'];
    return new AmpliaClient($ampliaEndpoint, $ampliaApiKey);
}

Python

from amplia_client import AmpliaClient

def get_amplia_client():
    api_key = current_app.config['AMPLIA_API_KEY']
    endpoint = current_app.config['AMPLIA_ENDPOINT']
    return AmpliaClient(endpoint, api_key)

.NET client

Lacuna.Amplia.Client 5.0.0 targets .NET Standard 2.0 and is built from the same source as Amplia 5.0.1. Get an IAmpliaService from dependency injection, after services.AddAmplia(...), or from AmpliaServicesFactory.GetService(endpoint, apiKey); the AmpliaClient class still works, but is marked [Obsolete].

using Lacuna.Amplia.Api;
using Lacuna.Amplia.Api.CertificateFormatting;
using Lacuna.Amplia.Api.Orders;
using Lacuna.Amplia.Client;

IAmpliaService amplia = AmpliaServicesFactory.GetService("https://amplia.lacunasoftware.com/", apiKey);

var order = await amplia.CreateOrderAsync(new CreateOrderRequest2<PkiBrazilCertificateParameters> {
	CAId = caId,
	Kind = CertificateKinds.PublicKey,
	ValidityEnd = DateTimeOffset.Now.AddYears(2),
	Parameters = new PkiBrazilCertificateParameters {
		Name = subjectName,
		Cpf = cpf,
		PhoneNumber = phoneNumber,
	},
});
string issueLink = await amplia.GetOrderIssueLinkAsync(order.Id, returnUrl);

In ASP.NET Core, services.AddAmplia(o => { o.Endpoint = …; o.ApiKey = …; }), or services.AddAmplia().Configure(configuration.GetSection("Amplia")), registers IAmpliaService; AmpliaOptions also has Timeout, Culture (sent as Accept-Language) and DefaultSubscriptionId.

Operation	.NET method	Endpoint
Create an order	CreateOrderAsync	POST /api/orders/{format} (POST /api/v2/orders for the non-generic request)
Get an order	GetOrderAsync	GET /api/v2/orders/{id}
Get the issue link	GetOrderIssueLinkAsync	GET /api/orders/{id}/issue-link
Email or text the issue link	SendIssueEmailAsync, SendIssueSmsAsync	POST /api/orders/{id}/send-issue-email-request, POST /api/v2/orders/{id}/send-issue-sms-request
Get the QR code	GetOrderIssueQRCodeDataAsync, GetOrderIssueQRCodeImageAsync	GET /api/orders/{id}/issue-qrcode-data, issue-qrcode-image
Issue from a CSR	IssueCertificateAsync	POST /api/v2/certificates
Issue a PKCS #12 file	IssuePkcs12CertificateAsync	POST /api/certificates/pkcs12
Get a certificate	GetCertificateAsync	GET /api/v2/certificates/{id}
Revoke a certificate	RevokeCertificateAsync	DELETE /api/certificates/{id}

API errors (422) throw AmpliaException, whose Code is the error code, or OrderLockedException when the code is OrderLocked.

How issuance works

Every certificate starts with an order on a CA, which holds the holder's data and the certificate's validity. The order is then fulfilled, issuing one certificate, in one of these ways:

Where the key pair is made	How you issue	Page
On the holder's computer, by Amplia's issue page	Send the holder an issue link	Issue on the holder's machine
On your server, or in the user's browser with Web PKI	Send Amplia a CSR	Issue from a CSR
By Amplia, which returns it in a password-protected file	Ask for a PKCS #12 (.pfx)	Issue a PKCS #12 file
No key pair: the certificate attests an attribute of the holder	Issue without a CSR	Attribute certificates

Start with Create certificate orders. Then:

• Issue on the holder's machine
• Issue from a CSR
• Issue a PKCS #12 file
• Attribute certificates
• Revoke certificates
• Errors

Webhook

Amplia can notify your system whenever a certificate is issued: the notification body is a WebhookEventModel whose type is OrderCertificateIssued, with the order and, once issued, the certificate.

The webhook belongs to the subscription. A user with the Admin or Manager role sets it on the dashboard, under Settings > Webhook configuration:

• Enable webhook, the URL that Amplia posts the notification to, and the Authentication type, which decides the header Amplia sends with each notification:

  Authentication type	Header
  NoAuth	No authentication header
  Bearer	Authorization: Bearer <token>
  ApiKey	X-Api-Key: <key>
  CustomAuthorizationHeader	Authorization: <scheme> <value>
  Basic	Authorization: Basic <value> (see the caution below)

• The Recent calls tab lists the notifications sent, with the status code and, for failed calls, the response.

Amplia sends a POST with a JSON body and counts any 2xx answer as delivered. The JSON keeps the property names of Amplia's models, in PascalCase (Type, Order, Certificate), with enums as names:

{
  "Type": "OrderCertificateIssued",
  "Order": { "Id": "…", "Status": "Issued", "CertificateId": "…" },
  "Certificate": { "Id": "…" }
}

Basic authentication

With Basic, the dashboard encodes the user name and the password separately and joins them with a colon, base64(user):base64(password), instead of the standard base64(user:password). A standard Basic authentication handler rejects that value, so prefer Bearer, ApiKey or CustomAuthorizationHeader.

TODO(docs): whether and how often Amplia retries a failed notification.

See also

• Amplia quick reference
• Operation Guide
• Changelog