Skip to content

API Reference

CertifyClouds provides a comprehensive REST API for programmatic access to all features.

Overview

The CertifyClouds API allows you to:

  • Trigger and monitor discovery scans
  • Query assets, compliance, and alerts
  • Manage subscriptions and settings
  • Automate rotation and sync operations (PRO)

Base URL

https://your-certifyclouds-instance/api

Or for local development: 

http://localhost:8080/api

Authentication

All API endpoints (except /health and /auth/login) require authentication.

JWT Authentication

  1. Login to obtain a JWT token:
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

Response: 

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 28800
}

  1. Include token in subsequent requests:
curl http://localhost:8080/api/assets/discovery/assets \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The web UI uses HTTP-only cookies. For browser-based API access, authentication cookies are automatically included.

Response Format

All responses use JSON with camelCase field names.

Success Response

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "perPage": 20
  }
}

Error Response

{
  "error": "Error message",
  "detail": "Detailed explanation",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Code Meaning
200 Success
201 Created
400 Bad request
401 Unauthorized
403 Forbidden (license/permission)
404 Not found
429 Rate limited
500 Server error

Rate Limiting

API requests are rate limited:

Limit Default
Per minute 60 requests
Per hour 1000 requests

When exceeded, you'll receive a 429 response with Retry-After header.

API Sections

Quick Examples

Run a Discovery Scan

curl -X POST http://localhost:8080/api/assets/discovery/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "full"}'

Get All Assets

curl http://localhost:8080/api/assets/discovery/assets \
  -H "Authorization: Bearer $TOKEN"

Get Compliance Score

curl http://localhost:8080/compliance/score \
  -H "Authorization: Bearer $TOKEN"

Create Alert Rule

curl -X POST http://localhost:8080/alerts/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Expiring Secrets",
    "alert_type": "secret_expiring",
    "threshold_days": 30,
    "delivery_method": "email",
    "recipients": ["team@company.com"]
  }'

SDKs and Libraries

Currently, CertifyClouds provides a REST API. Community SDKs may be available in the future.

For now, you can use any HTTP client:

  • Python: requests, httpx
  • JavaScript: fetch, axios
  • Go: net/http
  • PowerShell: Invoke-RestMethod

Support

For API questions: