API Overview

Introduction to the Lamassu IoT API architecture, base URLs, and common patterns

The Lamassu IoT Platform provides a comprehensive REST API for managing certificate authorities, devices, keys, and related resources. All APIs follow RESTful principles with consistent patterns for authentication, pagination, filtering, and error handling.

Architecture

Lamassu’s API is organized into multiple services, each responsible for specific domain operations:

Service	Base URL	Description
CA Service	/api/ca/v1	Certificate Authority operations, certificate lifecycle, and issuance profiles
Device Manager	/api/devmanager/v1	Device inventory, lifecycle, and identity management
DMS Manager	/api/dmsmanager/v1	Device Management Service configuration and EST enrollment
KMS	/api/kms/v1	Key Management Service for cryptographic operations

API Design Principles

RESTful Resources

All endpoints follow REST conventions:

• GET - Retrieve resources
• POST - Create new resources
• PUT - Update existing resources (full replacement)
• PATCH - Partial updates (metadata only)
• DELETE - Remove resources

Consistent Response Format

List endpoints return paginated results with a standard structure:

{
  "list": [
    // Array of resource objects
  ],
  "next": "bookmark-token"
}

list · array · required

Array of resource objects matching the query

next · string

Pagination bookmark for the next page. Omitted if there are no more results.

Pagination

All list endpoints support cursor-based pagination:

page_size · integer · default: "25"

Number of results per page (maximum varies by endpoint)

bookmark · string

Bookmark token from the previous response’s next field

Example Request:

curl "https://your-instance.com/api/ca/v1/cas?page_size=50" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "list": [
    { "id": "ca-1", "certificate": {...} },
    { "id": "ca-2", "certificate": {...} }
  ],
  "next": "eyJpZCI6ImNhLTIiLCJ0cyI6MTcwOTU1MjQwMH0="
}

To retrieve the next page:

curl "https://your-instance.com/api/ca/v1/cas?bookmark=eyJpZCI6ImNhLTIiLCJ0cyI6MTcwOTU1MjQwMH0=" \
  -H "Authorization: Bearer $TOKEN"

Sorting

List endpoints support server-side sorting:

sort_by · string

Field name to sort by (e.g., creation_ts, status, id)

sort_mode · string · default: "asc"

Sort direction: asc (ascending) or desc (descending)

Example:

curl "https://your-instance.com/api/ca/v1/cas?sort_by=creation_ts&sort_mode=desc" \
  -H "Authorization: Bearer $TOKEN"

For advanced sorting on JSON fields, see Filtering and Sorting.

Common Response Codes

The API uses standard HTTP status codes:

Code	Status	Meaning
200	OK	Request succeeded
201	Created	Resource successfully created
204	No Content	Successful deletion (no response body)
400	Bad Request	Invalid request parameters or validation error
401	Unauthorized	Missing or invalid authentication
404	Not Found	Resource does not exist
409	Conflict	Resource already exists or operation conflicts with current state
500	Internal Server Error	Server-side error

Error Response Format

All error responses include a JSON body with the error message:

{
  "err": "CA with id 'my-ca' not found"
}

err · string · required

Human-readable error message describing what went wrong

Example Error Scenarios:

400 Bad Request

{
  "err": "invalid certificate serial number format"
}

Common Patterns

Resource Identifiers

Resources are typically identified by:

• ID: Alphanumeric identifier (e.g., my-ca, device-123)
• Serial Number: For certificates (e.g., hexadecimal string)
• Path Parameters: Embedded in the URL (e.g., /cas/{id})

Metadata Management

Most resources support custom metadata via dedicated endpoints:

• PUT /resource/{id}/metadata - Replace all metadata
• PATCH /resource/{id}/metadata - Update specific metadata fields

Metadata operations use JSON Patch format:

{
  "patches": [
    {
      "op": "add",
      "path": "/environment",
      "value": "production"
    },
    {
      "op": "replace",
      "path": "/region",
      "value": "us-west-2"
    },
    {
      "op": "remove",
      "path": "/temporary_flag"
    }
  ]
}

Status Updates

Certificates and CAs support status transitions via POST to /status endpoints:

curl -X POST "https://your-instance.com/api/ca/v1/certificates/{sn}/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "REVOKED",
    "revocation_reason": "key_compromise"
  }'

Timestamp Format

All timestamps use ISO 8601 format with UTC timezone:

{
  "creation_ts": "2026-03-09T14:32:00Z",
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_to": "2027-01-01T00:00:00Z"
}

Rate Limiting

The API does not currently enforce global rate limits, but clients should implement:

• Exponential backoff for retry logic
• Connection pooling for concurrent requests
• Respect for Retry-After headers if present

Versioning

The API version is included in the base URL path (e.g., /api/ca/v1). Breaking changes will result in a new API version (v2, v3, etc.), with the previous version maintained for backward compatibility.

Next Steps

Authentication

Learn about JWT bearer tokens and mTLS authentication

Filtering & Sorting

Advanced filtering with JSONPath and server-side sorting

CA API

Manage certificate authorities and certificates

Device API

Device lifecycle and identity management