Certificates

Certificate issuance and management operations

List All Certificates

Retrieve a paginated list of all certificates across all CAs.

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 certificate objects

serial_number · string

Certificate serial number

subject · object

Certificate subject information (common_name, organization, etc.)

issuer · object

Issuer subject information

status · string

Certificate status: ACTIVE, EXPIRED, REVOKED, or INACTIVE

type · string

Certificate type: MANAGED, IMPORTED_WITH_KEY, or IMPORTED_WITHOUT_KEY

valid_from · string

Validity start timestamp (ISO 8601)

valid_to · string

Validity end timestamp (ISO 8601)

key_metadata · object

Key algorithm, size, and strength information

issuer_metadata · object

CA serial number, ID, and hierarchy level

metadata · object

Custom metadata key-value pairs

revocation_timestamp · string

Revocation timestamp if status is REVOKED

revocation_reason · string

Reason for revocation if applicable

next · string

Pagination bookmark for next page

Example Request

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

Example Response

{
  "list": [
    {
      "serial_number": "a1b2c3d4e5f67890",
      "subject": {
        "common_name": "device-001.iot.example.com",
        "organization": "Lamassu IoT"
      },
      "issuer": {
        "common_name": "Intermediate CA"
      },
      "status": "ACTIVE",
      "type": "MANAGED",
      "valid_from": "2024-01-15T10:00:00Z",
      "valid_to": "2025-01-15T10:00:00Z",
      "key_metadata": {
        "type": "RSA",
        "bits": 2048,
        "strength": "medium"
      },
      "issuer_metadata": {
        "serial_number": "1a2b3c4d",
        "id": "intermediate-ca-1",
        "level": 1
      },
      "metadata": {
        "device_type": "sensor",
        "location": "warehouse-a"
      }
    }
  ],
  "next": "eyJsYXN0X3NuIjoiYTFiMmMzZDQifQ=="
}

---

List Certificates by Status

Retrieve certificates filtered by a specific status.

Path Parameters

status · string · required

Certificate status: ACTIVE, EXPIRED, REVOKED, or INACTIVE

Query Parameters

Supports standard pagination and filtering parameters.

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/certificates/status/ACTIVE" \
  -H "Authorization: Bearer <token>"

---

List Certificates by Expiration

Retrieve certificates expiring within a specific time window.

Query Parameters

expires_after · string

Start of expiration window (ISO 8601 timestamp)

expires_before · string

End of expiration window (ISO 8601 timestamp)

page_size · integer · default: "25"

Number of results per page

bookmark · string

Pagination cursor

sort_by · string

Field to sort results by

sort_mode · string

Sort order: asc or desc

filter · string

Filter expression

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/certificates/expiration?expires_before=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"

---

Get Certificate by Serial Number

Retrieve a specific certificate by its serial number.

Path Parameters

sn · string · required

Certificate serial number

Example Request

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

---

List Certificates by CA

List all certificates issued by a specific CA.

Path Parameters

id · string · required

Certificate authority identifier

Query Parameters

Supports standard pagination and filtering parameters.

Example Request

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

---

List Certificates by CA and Status

List certificates issued by a specific CA filtered by status.

Path Parameters

id · string · required

Certificate authority identifier

status · string · required

Certificate status: ACTIVE, EXPIRED, REVOKED, or INACTIVE

Query Parameters

Supports standard pagination and filtering parameters.

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/cas/intermediate-ca-1/certificates/status/ACTIVE" \
  -H "Authorization: Bearer <token>"

---

Get Certificate by CA and Serial Number

Retrieve a certificate by its serial number for a specific CA.

Path Parameters

id · string · required

Certificate authority identifier

sn · string · required

Certificate serial number

Example Request

curl -X GET "https://your-domain.com/api/ca/v1/cas/intermediate-ca-1/certificates/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer <token>"

---

Sign Certificate (Issue from CSR)

Sign a Certificate Signing Request (CSR) with a CA to issue a new certificate.

Path Parameters

id · string · required

Certificate authority identifier

Request Body

csr · object · required

X509 certificate signing request (parsed representation)

profile_id · string

Issuance profile ID to use (alternative to inline profile)

profile · object

Complete issuance profile specification (alternative to profile_id)

Response

Returns the issued certificate object.

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/intermediate-ca-1/certificates/sign" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "csr": {
      "subject": {
        "common_name": "device-002.iot.example.com"
      },
      "public_key": "..."
    },
    "profile_id": "iot-device-profile"
  }'

---

Import Certificate

Import an existing certificate into the system.

Request Body

certificate · object · required

X509 certificate (parsed representation)

metadata · object

Custom metadata key-value pairs

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/certificates/import" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": {
      "subject": {
        "common_name": "imported-device.example.com"
      }
    },
    "metadata": {
      "source": "external-ca"
    }
  }'

---

Update Certificate Status

Update the status of a certificate (e.g., to revoke it).

Path Parameters

sn · string · required

Certificate serial number

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 PUT "https://your-domain.com/api/ca/v1/certificates/a1b2c3d4e5f67890/status" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "REVOKED",
    "revocation_reason": "Key compromise"
  }'

---

Update Certificate Metadata

Replace certificate metadata entirely using JSON patch operations.

Path Parameters

sn · string · required

Certificate serial number

Request Body

patches · array · required

Array of JSON patch operations

op · 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

Example Request

curl -X PUT "https://your-domain.com/api/ca/v1/certificates/a1b2c3d4e5f67890/metadata" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "patches": [
      {
        "op": "replace",
        "path": "/location",
        "value": "warehouse-b"
      }
    ]
  }'

---

Patch Certificate Metadata

Partially update certificate metadata.

Path Parameters

sn · string · required

Certificate serial number

Request Body

Same as Update Certificate Metadata (JSON patch operations).

---

Delete Certificate

Delete a certificate from the system.

Path Parameters

sn · string · required

Certificate serial number

Response

Returns 204 No Content on successful deletion.

Example Request

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

---

Sign Arbitrary Message

Sign an arbitrary message using a CA’s private key.

Path Parameters

id · string · required

Certificate authority identifier

Request Body

message · string · required

Base64-encoded message to sign

message_type · string · required

Type of message being signed

signature_algorithm · string · required

Signature algorithm to use

Response

signed_data · string

Base64-encoded signature

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/root-ca-1/signature/sign" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "SGVsbG8gV29ybGQ=",
    "message_type": "raw",
    "signature_algorithm": "SHA256WithRSA"
  }'

Example Response

{
  "signed_data": "YXNkZmFzZGZhc2Rm..."
}

---

Verify Signature

Verify a signature using a CA’s public key.

Path Parameters

id · string · required

Certificate authority identifier

Request Body

signature · string · required

Base64-encoded signature to verify

message · string · required

Base64-encoded original message

message_type · string · required

Type of message

signature_algorithm · string · required

Signature algorithm used

Response

valid · boolean

Whether the signature is valid

Example Request

curl -X POST "https://your-domain.com/api/ca/v1/cas/root-ca-1/signature/verify" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "YXNkZmFzZGZhc2Rm...",
    "message": "SGVsbG8gV29ybGQ=",
    "message_type": "raw",
    "signature_algorithm": "SHA256WithRSA"
  }'

Example Response

{
  "valid": true
}