API Reference

The Compliance Scorecard API provides RESTful endpoints for managing compliance, assessments, policies, and integrations. The API uses JSON for request and response payloads.

RESTful Design

Standard HTTP methods and status codes

JSON Responses

Structured data in JSON format

API Versioning

v3 and v4 API versions available

Base URLs

Environment	Base URL	Description
Development	`https://dev-api.compliancerisk.io`	Development and testing
Staging	`https://staging-api.compliancerisk.io`	Pre-production testing
Production	`https://go-api.compliancerisk.io`	Live production API

Authentication

The API uses Bearer token authentication with JWT tokens provided by Auth0.

Authentication Header

Authorization: Bearer <your-jwt-token>

Include this header in all API requests. Tokens are obtained through the Auth0 authentication flow.

Token Lifecycle

Expiration: Tokens expire after 24 hours
Refresh: Use Auth0 silent refresh for new tokens
Revocation: Tokens can be revoked at any time
Scope: Tokens include user permissions and roles

Error Responses

Status	Description
`401`	Missing or invalid token
`403`	Insufficient permissions
`429`	Rate limit exceeded

Rate Limiting

API requests are rate-limited to prevent abuse and ensure fair usage across all clients.

Rate Limits

Endpoint Category	Limit	Window
General API	1000 requests	1 hour
Authentication	100 requests	15 minutes
File Uploads	50 requests	1 hour
Reports	20 requests	1 hour

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

X-RateLimit-Limit: Maximum requests per window
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

Authentication Endpoints

GET /api/v3/auth/user

Get Current User Profile

Retrieves the authenticated user's profile information including roles and permissions.

Response Example

{
  "success": true,
  "data": {
    "id": "abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": {
      "id": "8QM9M7QM3",
      "name": "msp_admin",
      "display_name": "MSP Administrator"
    },
    "company": {
      "id": "company123",
      "name": "Example MSP",
      "subscription_status": "active"
    },
    "permissions": [
      "manage_policies",
      "view_assessments",
      "manage_users"
    ],
    "current_client_id": "client456"
  }
}

POST /api/v3/auth/logout-user

Logout Current User

Logs out the current user and invalidates their session.

Response Example

{
  "success": true,
  "message": "User logged out successfully"
}

User Management

GET /api/v4/users

Get All Users

Retrieves a list of all users accessible to the authenticated user based on their role and permissions.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number for pagination (default: 1)
`per_page`	integer	Optional	Items per page (default: 15, max: 100)
`role`	string	Optional	Filter by user role
`company_id`	string	Optional	Filter by company

Response Example

{
  "success": true,
  "data": [
    {
      "id": "user123",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": {
        "name": "company_user",
        "display_name": "Company User"
      },
      "company": {
        "id": "comp456",
        "name": "Client Company"
      },
      "status": "Active",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 45,
    "last_page": 3
  }
}

Company Management

GET /api/v3/companies

Get Companies

Retrieves companies accessible to the authenticated user. Super admins see all companies, while other users see only their own company.

Response Example

{
  "success": true,
  "data": [
    {
      "id": "comp123",
      "name": "Example MSP Company",
      "email": "contact@examplemsp.com",
      "subscription_status": "active",
      "subscription_package": "plus",
      "client_count": 25,
      "user_count": 8,
      "created_at": "2023-06-15T09:00:00Z",
      "subscription_cycle_end_date": "2025-06-15T00:00:00Z"
    }
  ]
}

GET /api/v3/companies/{companyId}

Get Company Details

Retrieves detailed information about a specific company.

Path Parameters

Parameter	Type	Required	Description
`companyId`	string	Required	Unique company identifier

Client Management

GET /api/v3/companies/{companyId}/clients

Get Company Clients

Retrieves all clients belonging to a specific company.

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by client status (ACTIVE, INACTIVE)
`search`	string	Optional	Search clients by name

Response Example

{
  "success": true,
  "data": [
    {
      "id": "client123",
      "name": "Acme Corporation",
      "status": "ACTIVE",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "email_delivery_settings": "SMTP",
      "policy_count": 15,
      "assessment_count": 8,
      "created_at": "2023-08-20T14:30:00Z"
    }
  ]
}

POST /api/v3/companies/{companyId}/clients

Create New Client

Creates a new client for the specified company.

Request Body

{
  "name": "New Client Company",
  "city": "Los Angeles",
  "state": "CA",
  "country": "US",
  "email_delivery_settings": "SMTP",
  "industry": "Technology",
  "employee_count": 150
}

Body Parameters

Parameter	Type	Required	Description
`name`	string	Required	Client company name
`city`	string	Optional	Client city
`state`	string	Optional	Client state/province
`country`	string	Optional	Client country code

Policy Management

GET /api/v3/companies/{companyId}/clients/{clientId}/policies

Get Client Policies

Retrieves all policies for a specific client with filtering and pagination options.

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by policy status
`category_id`	string	Optional	Filter by category
`search`	string	Optional	Search policy titles

Response Example

{
  "success": true,
  "data": [
    {
      "id": "policy123",
      "title": "Information Security Policy",
      "description": "Comprehensive information security policy",
      "category": {
        "id": "cat456",
        "name": "Security"
      },
      "status": "published",
      "owner": {
        "id": "user789",
        "name": "Policy Owner"
      },
      "current_version": "2.1",
      "last_updated": "2025-02-15T16:45:00Z",
      "adoption_rate": 85.5
    }
  ]
}

POST /api/v3/companies/{companyId}/clients/{clientId}/policies

Create New Policy

Creates a new policy for the specified client.

Request Body

{
  "title": "New Security Policy",
  "description": "Policy description",
  "category_id": "cat123",
  "owner_id": "user456",
  "policy_type": "operational",
  "notes": "Internal policy notes"
}

Assessment System

GET /api/v3/companies/{companyId}/clients/{clientId}/assessment-events

Get Assessment Events

Retrieves assessment events (assessment instances) for a specific client.

Response Example

{
  "success": true,
  "data": [
    {
      "id": "event123",
      "name": "Q1 2025 Security Assessment",
      "template": {
        "id": "template456",
        "name": "NIST Cybersecurity Framework"
      },
      "status": "in_progress",
      "completion_percentage": 65.5,
      "score": 78.2,
      "started_at": "2025-01-15T09:00:00Z",
      "completed_at": null,
      "version": "1.0"
    }
  ]
}

GET /api/v3/companies/{companyId}/clients/{clientId}/assessment-templates

Get Assessment Templates

Retrieves available assessment templates for creating new assessments.

Query Parameters

Parameter	Type	Required	Description
`global`	boolean	Optional	Include global templates
`category`	string	Optional	Filter by template category

External Integrations

GET /api/v3/companies/{companyId}/clients/{clientId}/api-keys

Get Integration API Keys

Retrieves configured API keys for external integrations.

Response Example

{
  "success": true,
  "data": [
    {
      "id": "key123",
      "type": "connectwise",
      "name": "ConnectWise Integration",
      "status": "active",
      "last_sync": "2025-02-20T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "key456",
      "type": "huntress",
      "name": "Huntress Security",
      "status": "active",
      "last_sync": "2025-02-20T11:15:00Z",
      "created_at": "2025-01-15T00:00:00Z"
    }
  ]
}

POST /api/v3/companies/{companyId}/clients/{clientId}/api-keys

Create Integration API Key

Creates a new API key configuration for external service integration.

Request Body

{
  "type": "connectwise",
  "name": "Main ConnectWise Instance",
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "server_url": "https://your-connectwise-server.com",
  "client_id": "your-client-id"
}

Security Note: API keys and secrets are encrypted before storage and never returned in API responses.

Error Handling

The API uses standard HTTP status codes and returns structured error responses.

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`422`	Validation Error
`429`	Rate Limited
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "email": [
        "The email field is required."
      ],
      "password": [
        "The password must be at least 8 characters."
      ]
    }
  }
}

Common Error Codes

VALIDATION_ERROR - Request validation failed
UNAUTHORIZED - Authentication required
FORBIDDEN - Insufficient permissions
NOT_FOUND - Resource not found
RATE_LIMITED - Too many requests

Webhooks

The API supports webhooks for real-time notifications of important events.

Supported Events

Policy Events

policy.created
policy.updated
policy.published
policy.approved
policy.rejected

Assessment Events

assessment.started
assessment.completed
assessment.scored
assessment.failed

Webhook Payload Example

{
  "event": "policy.published",
  "timestamp": "2025-02-20T15:30:00Z",
  "data": {
    "policy_id": "policy123",
    "title": "Updated Security Policy",
    "client_id": "client456",
    "version": "2.1",
    "published_by": "user789"
  }
}