Auditor Workflow API

Full audit lifecycle management — create audits, invite external auditors via magic-link, manage evidence requests, track findings, and generate reports. Requires Business tier or higher.

🔐 Two Auth Contexts

This API has two scopes: Customer endpoints (/api/v1/audits/*) use standard JWT auth. Auditor endpoints (/api/v1/auditor/*) use a separate auditor JWT obtained via magic-link invitation.

Customer Endpoints

POST /api/v1/audits 🔒
Create a new audit.

Request Body

FieldTypeRequiredDescription
framework_idstringYesFramework to audit against (e.g. soc2)
typestringYestype_i or type_ii
titlestringYesAudit title
descriptionstringNoAudit description
target_completionstringNoTarget date (ISO 8601)
 
curl -X POST https://api.privabase.com/api/v1/audits \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_id": "soc2",
    "type": "type_ii",
    "title": "SOC 2 Type II Annual Audit 2026",
    "target_completion": "2026-06-30T00:00:00Z"
  }'
// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/audits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    framework_id: 'soc2',
    type: 'type_ii',
    title: 'SOC 2 Type II Annual Audit 2026'
  })
});
# Python
resp = requests.post('https://api.privabase.com/api/v1/audits',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'framework_id': 'soc2',
        'type': 'type_ii',
        'title': 'SOC 2 Type II Annual Audit 2026'
    })

Response 201

{
  "data": {
    "id": "audit-abc-123",
    "framework_id": "soc2",
    "type": "type_ii",
    "title": "SOC 2 Type II Annual Audit 2026",
    "status": "draft",
    "created_at": "2026-03-14T10:30:00Z"
  }
}
GET /api/v1/audits 🔒
List all audits for the account.
curl https://api.privabase.com/api/v1/audits \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/v1/audits/:id 🔒
Get audit detail with progress metrics and recent activity log.
curl https://api.privabase.com/api/v1/audits/audit-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": {
    "id": "audit-abc-123",
    "title": "SOC 2 Type II Annual Audit 2026",
    "status": "in_progress",
    "progress": {
      "total_controls": 42,
      "reviewed": 28,
      "passed": 24,
      "failed": 3,
      "needs_evidence": 1,
      "pending": 14
    },
    "recent_activity": [
      { "type": "control_reviewed", "control_id": "CC6.1", "status": "passed", "at": "2026-03-14T10:30:00Z" }
    ]
  }
}
PUT /api/v1/audits/:id 🔒
Update audit details (title, description, status, target_completion).

Status Values

draft → in_progress → evidence_review → findings → complete

POST /api/v1/audits/:id/invite-auditor 🔒
Invite an external auditor via email. Sends a magic-link that grants auditor-scoped access.

Request Body

FieldTypeRequiredDescription
emailstringYesAuditor's email
namestringYesAuditor's name
firmstringNoAudit firm name
 
curl -X POST https://api.privabase.com/api/v1/audits/audit-abc-123/invite-auditor \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "auditor@firm.com",
    "name": "Jane Smith",
    "firm": "Big4 Audit LLP"
  }'
GET /api/v1/audits/:id/findings 🔒
List all findings for an audit.
GET /api/v1/audits/:id/evidence-requests 🔒
List evidence requests from the auditor for this audit.
POST /api/v1/audits/:id/evidence-requests/:rid/respond 🔒
Upload evidence in response to an auditor's evidence request.

Request Body

{ "evidence_file_url": "https://storage.privabase.com/evidence/screenshot.png" }
POST /api/v1/audits/:id/report 🔒
Generate a complete audit report (Markdown format) with findings, evidence summary, and control status.
curl -X POST https://api.privabase.com/api/v1/audits/audit-abc-123/report \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": {
    "report": "# SOC 2 Type II Audit Report\n\n## Executive Summary\n...",
    "format": "markdown"
  }
}
GET /api/v1/audits/:id/activity 🔒
Get the full activity log for an audit.

Auditor Portal Endpoints

These endpoints use a separate auditor JWT obtained via the magic-link invitation flow.

POST /api/v1/auditor/accept-invitation
Accept an audit invitation via magic-link token. Returns an auditor-scoped JWT. No authentication required.

Request Body

{ "token": "magic-link-token-from-email" }
curl -X POST https://api.privabase.com/api/v1/auditor/accept-invitation \
  -H "Content-Type: application/json" \
  -d '{ "token": "magic-link-token-from-email" }'

Response

{
  "data": {
    "token": "eyJ...(auditor JWT)",
    "audit": {
      "id": "audit-abc-123",
      "title": "SOC 2 Type II Annual Audit 2026",
      "framework_id": "soc2"
    }
  }
}
GET /api/v1/auditor/audit 🔒 Auditor JWT
Get the audit the auditor is assigned to, with progress metrics.
GET /api/v1/auditor/controls 🔒 Auditor JWT
List all controls for the audit's framework.
GET /api/v1/auditor/controls/:id/evidence 🔒 Auditor JWT
View all evidence submitted for a specific control.
PUT /api/v1/auditor/controls/:id/status 🔒 Auditor JWT
Mark a control as passed, failed, or needs-evidence.

Request Body

FieldTypeRequiredDescription
statusstringYespending, passed, failed, needs_evidence
auditor_notesstringNoAuditor notes
evidence_sufficientbooleanNoWhether evidence is sufficient
 
curl -X PUT https://api.privabase.com/api/v1/auditor/controls/ctrl-001/status \
  -H "Authorization: Bearer AUDITOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "passed",
    "auditor_notes": "Evidence verified — MFA enforced for all users",
    "evidence_sufficient": true
  }'
POST /api/v1/auditor/evidence-requests 🔒 Auditor JWT
Request additional evidence from the customer.

Request Body

FieldTypeRequiredDescription
control_idstringYesRelated control ID
descriptionstringYesWhat evidence is needed
prioritystringNolow, medium, high, critical
POST /api/v1/auditor/findings 🔒 Auditor JWT
Create an audit finding.

Request Body

FieldTypeRequiredDescription
control_idstringYesRelated control
severitystringYescritical, major, minor, observation
titlestringYesFinding title
descriptionstringYesFinding description
remediationstringNoRecommended remediation
 
curl -X POST https://api.privabase.com/api/v1/auditor/findings \
  -H "Authorization: Bearer AUDITOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "control_id": "ctrl-007",
    "severity": "major",
    "title": "Incomplete access review logs",
    "description": "Access reviews lack evidence of quarterly cadence",
    "remediation": "Implement quarterly access review with documented sign-off"
  }'
GET /api/v1/auditor/findings 🔒 Auditor JWT
List all findings for this audit.
PUT /api/v1/auditor/findings/:id 🔒 Auditor JWT
Update a finding's status (open, in_progress, resolved, accepted) or details.
POST /api/v1/auditor/complete 🔒 Auditor JWT
Mark the audit as complete.
curl -X POST https://api.privabase.com/api/v1/auditor/complete \
  -H "Authorization: Bearer AUDITOR_JWT"

PrivaBase API v1.3.0 · privabase.com