Compliance

Overview

The Compliance API provides endpoints for managing and monitoring regulatory compliance. Features include access reviews, data retention policies, and compliance reports.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/compliance/status	Get compliance status
GET	/api/admin/compliance/access-reviews	List access reviews
POST	/api/admin/compliance/access-reviews	Create access review
GET	/api/admin/compliance/access-reviews/:id	Get access review details
POST	/api/admin/compliance/access-reviews/:id/items/:itemId/approve	Approve review item
POST	/api/admin/compliance/access-reviews/:id/items/:itemId/revoke	Revoke review item
POST	/api/admin/compliance/access-reviews/:id/complete	Complete access review
GET	/api/admin/data-retention/status	Get data retention status
PUT	/api/admin/data-retention/policies	Update data retention policies

---

Get Compliance Status

Retrieve an overview of the tenant’s compliance status.

Endpoint

GET /api/admin/compliance/status

Request Example

curl -X GET "https://{tenant-domain}/api/admin/compliance/status" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "overall_status": "compliant",
  "last_updated_at": 1706140800,
  "categories": [
    {
      "name": "access_control",
      "display_name": "Access Control",
      "status": "compliant",
      "checks": [
        {
          "name": "mfa_enabled",
          "display_name": "MFA Enabled",
          "status": "passed",
          "message": "MFA is enabled"
        },
        {
          "name": "password_policy",
          "display_name": "Password Policy",
          "status": "passed",
          "message": "Password policy is configured"
        }
      ]
    },
    {
      "name": "audit_logging",
      "display_name": "Audit Logging",
      "status": "compliant",
      "checks": [
        {
          "name": "audit_log_enabled",
          "display_name": "Audit Log Enabled",
          "status": "passed",
          "message": "Audit logging is enabled"
        },
        {
          "name": "audit_log_retention",
          "display_name": "Audit Log Retention",
          "status": "passed",
          "message": "Retention period: 365 days"
        }
      ]
    },
    {
      "name": "access_review",
      "display_name": "Access Review",
      "status": "warning",
      "checks": [
        {
          "name": "periodic_review",
          "display_name": "Periodic Review",
          "status": "warning",
          "message": "Next review due in 7 days"
        }
      ]
    }
  ],
  "pending_actions": [
    {
      "type": "access_review",
      "message": "Access review is approaching deadline",
      "due_date": "2024-01-29"
    }
  ]
}

---

List Access Reviews

Retrieve a list of access reviews.

Endpoint

GET /api/admin/compliance/access-reviews

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 20)
cursor	string	-	Pagination cursor
status	string	-	Filter by status

Review Status

Status	Description
draft	Draft
in_progress	In progress
completed	Completed
expired	Expired

Request Example

curl -X GET "https://{tenant-domain}/api/admin/compliance/access-reviews?status=in_progress" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "review_abc123",
      "name": "Q1 2024 Access Review",
      "type": "quarterly",
      "status": "in_progress",
      "scope": {
        "type": "role",
        "roles": ["admin", "editor"]
      },
      "progress": {
        "total_items": 50,
        "reviewed_items": 30,
        "approved": 25,
        "revoked": 5
      },
      "due_date": "2024-01-31",
      "created_at": 1705881600,
      "created_by": "usr_admin001"
    }
  ],
  "total": 5,
  "cursor": null
}

---

Create Access Review

Create a new access review.

Endpoint

POST /api/admin/compliance/access-reviews

Request Body

Field	Type	Required	Description
name	string	✓	Review name
type	string	✓	Review type
scope	object	✓	Review scope
due_date	string	✓	Due date (ISO 8601 format)
reviewers	string[]	✓	Reviewer user IDs
description	string	-	Description

Review Types

Type	Description
quarterly	Quarterly review
annual	Annual review
ad_hoc	Ad-hoc review
certification	Certification review

Request Example

curl -X POST "https://{tenant-domain}/api/admin/compliance/access-reviews" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Admin Privileges Review",
    "type": "quarterly",
    "scope": {
      "type": "role",
      "roles": ["tenant_admin", "system_admin"]
    },
    "due_date": "2024-03-31",
    "reviewers": ["usr_reviewer001", "usr_reviewer002"],
    "description": "Quarterly admin privileges review"
  }'

Response Example

{
  "id": "review_xyz789",
  "name": "Q1 2024 Admin Privileges Review",
  "status": "draft",
  "scope": {
    "type": "role",
    "roles": ["tenant_admin", "system_admin"]
  },
  "progress": {
    "total_items": 15,
    "reviewed_items": 0
  },
  "due_date": "2024-03-31",
  "created_at": 1706140800
}

---

Get Access Review Details

Retrieve details for a specified access review.

Endpoint

GET /api/admin/compliance/access-reviews/:id

Request Example

curl -X GET "https://{tenant-domain}/api/admin/compliance/access-reviews/review_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "review_abc123",
  "name": "Q1 2024 Access Review",
  "type": "quarterly",
  "status": "in_progress",
  "scope": {
    "type": "role",
    "roles": ["admin", "editor"]
  },
  "progress": {
    "total_items": 50,
    "reviewed_items": 30,
    "approved": 25,
    "revoked": 5
  },
  "items": [
    {
      "id": "item_001",
      "user_id": "usr_abc123",
      "user_email": "[email protected]",
      "user_name": "John Doe",
      "role": "admin",
      "granted_at": 1673345600,
      "granted_by": "usr_admin001",
      "status": "pending",
      "last_activity_at": 1706054400
    },
    {
      "id": "item_002",
      "user_id": "usr_def456",
      "user_email": "[email protected]",
      "user_name": "Jane Smith",
      "role": "editor",
      "granted_at": 1688169600,
      "granted_by": "usr_admin001",
      "status": "approved",
      "reviewed_at": 1706054400,
      "reviewed_by": "usr_reviewer001"
    }
  ],
  "reviewers": [
    {
      "user_id": "usr_reviewer001",
      "user_name": "Reviewer 1",
      "reviewed_count": 30
    }
  ],
  "due_date": "2024-01-31",
  "created_at": 1705881600
}

---

Approve Review Item

Approve (maintain) access permissions.

Endpoint

POST /api/admin/compliance/access-reviews/:id/items/:itemId/approve

Request Body

Field	Type	Required	Description
comment	string	-	Comment

Request Example

curl -X POST "https://{tenant-domain}/api/admin/compliance/access-reviews/review_abc123/items/item_001/approve" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Confirmed necessary for business operations"
  }'

---

Revoke Review Item

Revoke (remove) access permissions.

Endpoint

POST /api/admin/compliance/access-reviews/:id/items/:itemId/revoke

Request Body

Field	Type	Required	Description
reason	string	✓	Reason for revocation
effective_date	string	-	Effective date of revocation (default: immediate)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/compliance/access-reviews/review_abc123/items/item_003/revoke" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "No longer required due to change in responsibilities",
    "effective_date": "2024-02-01"
  }'

---

Complete Access Review

Mark an access review as completed.

Endpoint

POST /api/admin/compliance/access-reviews/:id/complete

Request Example

curl -X POST "https://{tenant-domain}/api/admin/compliance/access-reviews/review_abc123/complete" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "review_abc123",
  "status": "completed",
  "completed_at": 1706140800,
  "summary": {
    "total_items": 50,
    "approved": 45,
    "revoked": 5
  }
}

---

Get Data Retention Status

Retrieve the status of data retention policies.

Endpoint

GET /api/admin/data-retention/status

Request Example

curl -X GET "https://{tenant-domain}/api/admin/data-retention/status" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "policies": [
    {
      "data_type": "audit_logs",
      "display_name": "Audit Logs",
      "retention_days": 365,
      "current_oldest": "2023-01-22",
      "records_count": 1250000,
      "next_purge_at": "2024-01-23T00:00:00Z"
    },
    {
      "data_type": "sessions",
      "display_name": "Session Data",
      "retention_days": 30,
      "current_oldest": "2023-12-23",
      "records_count": 50000,
      "next_purge_at": "2024-01-23T00:00:00Z"
    },
    {
      "data_type": "deleted_users",
      "display_name": "Deleted Users",
      "retention_days": 90,
      "current_oldest": "2023-10-24",
      "records_count": 150,
      "next_purge_at": "2024-01-23T00:00:00Z"
    }
  ],
  "last_purge_at": "2024-01-22T00:00:00Z",
  "next_purge_at": "2024-01-23T00:00:00Z"
}

---

Update Data Retention Policies

Update data retention policies.

Endpoint

PUT /api/admin/data-retention/policies

Request Body

Field	Type	Required	Description
policies	object[]	✓	List of policy settings

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/data-retention/policies" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "policies": [
      {
        "data_type": "audit_logs",
        "retention_days": 730
      },
      {
        "data_type": "sessions",
        "retention_days": 60
      }
    ]
  }'

Response Example

{
  "updated": true,
  "policies": [
    {
      "data_type": "audit_logs",
      "retention_days": 730
    },
    {
      "data_type": "sessions",
      "retention_days": 60
    }
  ],
  "updated_at": 1706140800
}