# API Module

SmartCMS provides a powerful and flexible **Application Programming Interface (API)** designed to allow external systems to integrate with all major SmartCMS functionalities.
The API exposes internal controller operations as secure web services, enabling interoperability with third‑party applications, portals, identity systems, and enterprise workflows.

Through this API, external systems can fully interact with SmartCMS and execute the same operations available in the system’s user interface.

# 1. Overview

The API module enables seamless interaction between SmartCMS and external systems. It allows programmatic access to:

- Enrolment request management
- Certificate lifecycle operations
- Device lifecycle operations
- Office and operator management
- Personal data and extended attributes
- Self‑service operations
- Audit and monitoring
- Integration with CA backends


All internal controller-level operations can be mapped to API endpoints.

# 2. Supported Protocols

SmartCMS supports common and standardized protocols to maximize compatibility:

- **JSON over HTTP**
- **REST (HTTP Representational State Transfer)**


These formats allow easy integration with enterprise applications, portals, identity systems, and workflow engines.

# 3. Available API Operations

SmartCMS exposes a broad set of operations for external consumption. These include:

## 3.1 Requests

- Create new enrolment requests
- Retrieve lists of requests
- Filter requests by status, date, operator, or office
- Retrieve full details of a specific request
- Update or enrich request metadata


## 3.2 Devices

- List all devices
- Retrieve detailed device information
- Query device state (active, suspended, revoked, expired)
- Fetch lifecycle history of a device
- Access production metadata


## 3.3 Certificates

- Issue certificates
- Batch issuance (if supported by the CA)
- Suspend certificates
- Reactivate suspended certificates
- Revoke certificates
- Renew certificates
- Fetch certificate metadata
- Retrieve profiles/templates for issuance


## 3.4 Organizations / Divisions / Offices

- List organizations
- List divisions
- List registration offices
- Retrieve office-level metadata
- Determine visibility scopes for operators


## 3.5 Operators

- List operators
- Retrieve operator details
- Create new operators
- Assign roles, permissions, and divisions
- Enable/disable accounts
- Batch import of operators via API


## 3.6 Personal Data Module

- Retrieve user personal data
- Update or extend personal data attributes
- Validate custom fields
- Integrate with external identity sources through API-assisted completion


## 3.7 Self-Service Portal Operations

- PIN reset
- Certificate renewal
- Temporary suspension
- Device lifecycle updates
- Request virtual tokens


## 3.8 Auditing

- Retrieve audit log entries
- Filter audit logs by operator, entity, date, action
- Retrieve per-object audit trail
- Export logs (CSV, XML, JSON)
- Validate signed audit logs


# 4. API Exposure and Configuration

Administrators may configure:

- Which endpoints are exposed externally
- Authentication type required for each endpoint
- Rate limits and throttling
- API access restrictions per client
- Allowed IP ranges
- Enable/disable complete API modules


All API exposure is controlled via configuration, ensuring security and compliance with RA/CA policies.

# 5. Authentication & Authorization

SmartCMS supports a variety of authentication models to secure API access.

## 5.1 API Key Authentication (Default)

Each client application receives an **API Key**, which is sent in the request headers.
API Keys:

- Identify the calling application
- Can be restricted to certain endpoints
- Support custom scopes
- Are fully revocable


## 5.2 Certificate-Based Authentication (optional)

Endpoints can require:

- mTLS (mutual TLS) with client certificates
- Identity certificates issued by a CA


## 5.3 Role-Based Access

Authorization depends on:

- Operator role
- Division / office assignment
- Explicit permissions for the endpoint


Examples:

- A Help Desk application can only call suspension/reactivation endpoints
- A self-service portal can only trigger operations for its token holder
- A batch production service can only access device issuance endpoints


# 6. Permissions and Scope Control

Each endpoint may be configured with:

- Role requirements
- Division/office constraints
- Special capabilities (e.g., “certificate:revoke”)
- Operational context restrictions


SmartCMS enforces strict separation of duties through RBAC.

# 7. Example API Use Cases

## 7.1 ERP/HR System Integration

- Automatic employee data import
- Automatic enrolment request creation
- Automatic office and division mapping


## 7.2 Integration with External CA Services

- Submitting CSR requests
- Fetching issued certificates
- Managing certificate state in bulk


## 7.3 CRM or Customer Portal Integration

- Checking device status for end users
- Triggering renewals
- Providing certificate download links


## 7.4 Security Operations Center (SOC)

- Real-time audit log retrieval
- Certificate lifecycle monitoring
- Device state change alerts


# 8. API Architecture

Internally, the SmartCMS API is tightly coupled with:

- SmartCMS controllers
- CA Service Gateway
- DB adapters
- Authentication providers
- Audit subsystem
- Personalization modules
- Self‑service workflows


Each API call maps to internal business logic, ensuring consistency with UI operations.

# 9. Extensibility

The API module is fully extensible and supports:

- Adding new endpoints
- Extending existing payloads
- Integrating custom modules
- Adapting authentication mechanisms
- Creating customer-specific workflows
- Overriding validation rules


SmartCMS uses an **Inversion of Control (IoC)** pattern, allowing modules to be replaced or extended via configuration.

# 10. Security and Compliance Notes

SmartCMS API is built to operate under strict RA/CA policies:

- All actions are logged and audited
- Sensitive data is sanitized
- API uses HTTPS/TLS mandatory
- API Keys must be rotated periodically
- Audit logging supports legally binding signatures
- Compliance with national and EU standards (eIDAS)


# 11. Example API Structure (High Level)

Non-binding examples showing typical structure:

- ET  /api/v1/requests
- POST /api/v1/requests
- GET  /api/v1/devices
- GET  /api/v1/devices/{id}
- POST /api/v1/certificates/{id}/suspend
- POST /api/v1/certificates/{id}/reactivate
- POST /api/v1/certificates/{id}/renew
- GET  /api/v1/operators
- POST /api/v1/operators
- GET  /api/v1/offices
- GET  /api/v1/audit


These endpoints illustrate typical REST semantics used by SmartCMS.

# Summary

The SmartCMS API module is a powerful middleware layer enabling:

- Complete integration with external information systems
- Full control over enrolment, devices, certificates, operators, offices
- Strong authentication and authorization
- Advanced auditing and compliance features
- CA-neutral integration workflows
- Automation of complete lifecycle operations


It transforms SmartCMS into a fully interoperable component of any large-scale identity management ecosystem.