Certificate Authorities

List Certificate Authorities

Retrieve a paginated list of all certificate authorities.

Query Parameters

page_size

integer

default:"25"

Number of results per page

bookmark

string

Pagination cursor from previous response

sort_by

string

Field to sort results by

sort_mode

string

Sort order: asc or desc

filter

string

Filter expression (e.g., status[eq]=ACTIVE)

Response

list

array

Array of CA certificate objects

string

CA identifier

serial_number

string

Certificate serial number

certificate

object

Certificate details including subject, issuer, validity, and status

level

integer

CA hierarchy level (0 for root CA)

profile_id

string

Associated issuance profile ID

metadata

object

Custom metadata key-value pairs

creation_ts

string

Creation timestamp (ISO 8601)

string

Pagination bookmark for next page

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/cas?page_size=10&sort_mode=desc" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "list": [
    {
      "id": "root-ca-1",
      "serial_number": "1a2b3c4d5e6f7890",
      "certificate": {
        "subject": {
          "common_name": "Root CA",
          "organization": "Lamassu IoT",
          "country": "US"
        },
        "status": "ACTIVE",
        "valid_from": "2024-01-01T00:00:00Z",
        "valid_to": "2034-01-01T00:00:00Z"
      },
      "level": 0,
      "profile_id": "default-ca-profile",
      "metadata": {
        "purpose": "production"
      },
      "creation_ts": "2024-01-01T00:00:00Z"
    }
  ],
  "next": "eyJsYXN0X2lkIjoicm9vdC1jYS0xIn0="
}

Create Certificate Authority

Create a new certificate authority.

Request Body

string

required

Unique CA identifier

subject

object

required

Certificate subject information

common_name

string

required

Common name (CN)

organization

string

Organization (O)

organization_unit

string

Organizational unit (OU)

country

string

Country (C)

state

string

State or province (ST)

locality

string

Locality or city (L)

key_metadata

object

required

Key generation parameters

type

string

required

Key type (e.g., RSA, ECDSA)

bits

integer

required

Key size in bits (e.g., 2048, 4096 for RSA; 256, 384 for ECDSA)

ca_expiration

object

required

CA certificate validity period

type

string

required

Validity type: Duration or Time

duration

string

Human-readable duration (e.g., 10y, 365d) - required if type is Duration

time

string

Expiration timestamp (ISO 8601) - required if type is Time

parent_id

string

Parent CA identifier (omit for root CA)

profile_id

string

Issuance profile ID for certificates issued by this CA

engine_id

string

Crypto engine identifier

metadata

object

Custom metadata key-value pairs

ca_issuance_profile_id

string

CA issuance profile ID (for creating subordinate CAs)

Response

Returns the created CA certificate object (see List CAs response for structure).

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "root-ca-prod",
    "subject": {
      "common_name": "Production Root CA",
      "organization": "Lamassu IoT",
      "country": "US"
    },
    "key_metadata": {
      "type": "RSA",
      "bits": 4096
    },
    "ca_expiration": {
      "type": "Duration",
      "duration": "10y"
    },
    "engine_id": "default-engine",
    "metadata": {
      "environment": "production"
    }
  }'

Import Certificate Authority

Import an existing certificate authority.

Request Body

string

required

CA identifier

engine_id

string

required

Crypto engine identifier

object

required

X509 certificate (parsed representation)

private_key

string

Base64-encoded PEM private key

ca_chain

array

Array of X509 certificate objects forming the chain

ca_type

string

required

Certificate type: MANAGED, IMPORTED_WITH_KEY, or IMPORTED_WITHOUT_KEY

parent_id

string

Parent CA identifier

profile_id

string

Issuance profile ID

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/import" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "imported-ca-1",
    "engine_id": "default-engine",
    "ca_type": "IMPORTED_WITH_KEY",
    "private_key": "LS0tLS1CRUdJTi...",
    "ca": {
      "subject": {
        "common_name": "Imported CA"
      }
    },
    "profile_id": "default-profile"
  }'

Get CA by ID

Retrieve a specific certificate authority by its identifier.

Path Parameters

string

required

Certificate authority identifier

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/cas/root-ca-prod" \
  -H "Authorization: Bearer <token>"

Get CAs by Common Name

Retrieve certificate authorities matching a specific common name.

Path Parameters

string

required

Common name to search for

Query Parameters

Supports standard pagination and filtering parameters (see List CAs).

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/cas/cn/Production%20Root%20CA" \
  -H "Authorization: Bearer <token>"

Update CA Metadata

Replace CA metadata entirely.

Path Parameters

string

required

Certificate authority identifier

Request Body

patches

array

required

Array of JSON patch operations

string

required

Operation: add, remove, replace, move, copy, or test

path

string

required

JSON pointer path to the target field

value

any

Value for the operation

from

string

Source path for move/copy operations

Example Request

curl -X PUT "https://your-domain.com/api/ca/v1/cas/root-ca-prod/metadata" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "patches": [
      {
        "op": "replace",
        "path": "/environment",
        "value": "staging"
      },
      {
        "op": "add",
        "path": "/owner",
        "value": "security-team"
      }
    ]
  }'

Patch CA Metadata

Partially update CA metadata.

Path Parameters

string

required

Certificate authority identifier

Request Body

Same as Update CA Metadata (JSON patch operations).

Update CA Status

Update the status of a certificate authority.

Path Parameters

string

required

Certificate authority identifier

Request Body

status

string

required

New status: ACTIVE, EXPIRED, REVOKED, or INACTIVE

revocation_reason

string

Reason for revocation (required when status is REVOKED)

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/root-ca-prod/status" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "REVOKED",
    "revocation_reason": "Key compromise"
  }'

Update CA Issuance Profile

Update the issuance profile used by a CA for issuing certificates.

Path Parameters

string

required

Certificate authority identifier

Request Body

profile_id

string

required

New issuance profile identifier

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/root-ca-prod/profile" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "new-profile-v2"
  }'

Reissue CA Certificate

Reissue an existing CA certificate with a new validity period. The CA must be in a valid state (not expired or revoked).

Path Parameters

string

required

Certificate authority identifier

Request Body

profile_id

string

ID of existing issuance profile to use (alternative to inline profile)

profile

object

Complete issuance profile specification (alternative to profile_id)

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/root-ca-prod/reissue" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "extended-validity-profile"
  }'

Delete CA

Delete a certificate authority.

Path Parameters

string

required

Certificate authority identifier

Response

Returns 204 No Content on successful deletion.

Example Request

curl -X DELETE "https://your-domain.com/api/ca/v1/cas/old-ca-1" \
  -H "Authorization: Bearer <token>"

API Overview

Certificate Authority API

Device Manager API

DMS Manager API

Key Management API

Alerts API

Validation Authority API

Documentation Index

​List Certificate Authorities

​Query Parameters

​Response

​Example Request

​Example Response

​Create Certificate Authority

​Request Body

​Response

​Example Request

​Import Certificate Authority

​Request Body

​Example Request

​Get CA by ID

​Path Parameters

​Example Request

​Get CAs by Common Name

​Path Parameters

​Query Parameters

​Example Request

​Update CA Metadata

​Path Parameters

​Request Body

​Example Request

​Patch CA Metadata

​Path Parameters

​Request Body

​Update CA Status

​Path Parameters

​Request Body

​Example Request

​Update CA Issuance Profile

​Path Parameters

​Request Body

​Example Request

​Reissue CA Certificate

​Path Parameters

​Request Body

​Example Request

​Delete CA

​Path Parameters

​Response

​Example Request

List Certificate Authorities

Query Parameters

Response

Example Request

Example Response

Create Certificate Authority

Request Body

Response

Example Request

Import Certificate Authority

Request Body

Example Request

Get CA by ID

Path Parameters

Example Request

Get CAs by Common Name

Path Parameters

Query Parameters

Example Request

Update CA Metadata

Path Parameters

Request Body

Example Request

Patch CA Metadata

Path Parameters

Request Body

Update CA Status

Path Parameters

Request Body

Example Request

Update CA Issuance Profile

Path Parameters

Request Body

Example Request

Reissue CA Certificate

Path Parameters

Request Body

Example Request

Delete CA

Path Parameters

Response

Example Request