Skip to main content

WF-006: Auditor Access Grant Workflow

Overview​

This workflow enables organizations to grant time-limited, read-only access to external auditors for compliance purposes (SOC 2, ISO 27001, GDPR audits). It creates secure access tokens with scoped permissions and comprehensive audit logging.

Trigger: HTTP POST to /grant-auditor-access endpoint Duration: ~2-3 seconds Related Workflows: None (standalone compliance workflow)

Prerequisites​

Before starting, ensure you have:

  • Required tools installed
  • Access to necessary resources
  • Basic understanding of concepts

Verify setup:

# Verification command

Workflow Diagram​

Auditor Access Flow

Step-by-Step Narrative​

Step 1: Access Request Received​

  • Node: Auditor Access Request
  • Type: HTTP POST Endpoint
  • Path: /grant-auditor-access
  • Actions:
    • Receives access grant request from admin console
    • Validates required fields: auditor_email, auditor_company, scope
    • Authenticates requesting admin
    • Verifies admin has owner-level permissions

Step 2: Validate and Generate Access​

  • Node: Validate and Generate Access
  • Type: Code (JavaScript)
  • Actions:
    • Validates auditor email format
    • Validates auditor company name provided
    • Generates 96-character secure access token
    • Calculates expiration (default 30 days, max 90 days)
    • Determines allowed resources based on scope:
      • security: audit_logs, access_reports, security_config
      • financial: billing_history, invoices, usage_reports
      • compliance: audit_logs, compliance_status, user_activity, access_reports
      • full: All of the above

Step 3: Create Auditor Access Record​

  • Node: Create Auditor Access Record
  • Type: PostgreSQL Insert
  • Table: public.auditor_access
  • Actions:
    • Creates unique access record
    • Stores organization ID and auditor details
    • Stores hashed access token
    • Records scope and allowed resources (JSON)
    • Sets status to active
    • Records granting admin and timestamp

Step 4: Send Auditor Access Email​

  • Node: Send Auditor Access Email
  • Type: Email Send
  • Actions:
    • Sends branded access notification to auditor
    • Includes organization name
    • Lists scope and access duration
    • Itemizes allowed resources
    • Provides secure access link
    • Notes read-only nature and logging
    • Sent from: compliance@coditect.ai

Step 5: Log Audit Event​

  • Node: Log Audit Event
  • Type: PostgreSQL Insert
  • Table: public.audit_log
  • Actions:
    • Creates immutable audit log entry
    • Records action: auditor_access_granted
    • Stores actor (admin who granted access)
    • Records auditor email, scope, expiration
    • Enables compliance reporting

Step 6: Return Success Response​

  • Node: Success Response
  • Type: Webhook Response
  • Actions:
    • Returns HTTP 200 with confirmation
    • Includes expiration timestamp
    • Includes granted scope summary
    • Admin can track access in dashboard

Data Flow​

Input:
{
  "org_id": "org-uuid",
  "org_name": "Acme Corp",
  "admin_id": "admin-uuid",
  "auditor_email": "auditor@kpmg.com",
  "auditor_company": "KPMG",
  "scope": "compliance",
  "access_days": 30
}

Database Record (auditor_access):
{
  "id": "access-uuid",
  "organization_id": "org-uuid",
  "auditor_email": "auditor@kpmg.com",
  "auditor_company": "KPMG",
  "access_token": "hashed-token",
  "scope": "compliance",
  "allowed_resources": ["audit_logs", "compliance_status", "user_activity", "access_reports"],
  "granted_by": "admin-uuid",
  "expires_at": "2024-02-15T10:00:00Z",
  "status": "active"
}

Output:
{
  "success": true,
  "message": "Auditor access granted",
  "expires_at": "2024-02-15T10:00:00Z",
  "scope": "compliance"
}

Access Scopes​

ScopeResources AccessibleUse Case
securityaudit_logs, access_reports, security_configSecurity audits, penetration test reviews
financialbilling_history, invoices, usage_reportsFinancial audits, SOX compliance
complianceaudit_logs, compliance_status, user_activity, access_reportsSOC 2, ISO 27001, GDPR audits
fullAll resourcesComprehensive annual audits

Auditor Dashboard Access​

When the auditor clicks the access link:

  1. Link format: https://app.coditect.ai/auditor/{token}
  2. Token validated against database
  3. Auditor dashboard loaded with:
    • Read-only views of allowed resources
    • Export buttons for each resource type
    • Activity timestamp for compliance evidence
  4. All actions logged to audit trail

Audit Trail Entry Format​

{
  "id": "log-uuid",
  "organization_id": "org-uuid",
  "actor_type": "admin",
  "actor_id": "admin-uuid",
  "action": "auditor_access_granted",
  "resource_type": "auditor_access",
  "details": {
    "auditor_email": "auditor@kpmg.com",
    "scope": "compliance",
    "expires_at": "2024-02-15T10:00:00Z"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Access Expiration​

  • Default: 30 days
  • Minimum: 1 day
  • Maximum: 90 days
  • Auto-revocation: Access automatically expires; no manual cleanup needed
  • Early revocation: Admin can manually revoke at any time

Error Handling​

ErrorCauseResponse
400 Bad RequestMissing auditor details{ "error": "Auditor email and company required" }
403 ForbiddenNot organization owner{ "error": "Only owners can grant auditor access" }
400 Bad RequestInvalid scope{ "error": "Invalid scope. Use: security, financial, compliance, full" }
400 Bad RequestDuration too long{ "error": "Maximum access duration is 90 days" }

Security Considerations​

  • Only organization owners can grant auditor access
  • Access tokens are 96-character cryptographic random
  • Tokens hashed in database (cannot be retrieved)
  • All auditor actions logged with IP and timestamp
  • Read-only access only (no write/delete capabilities)
  • Separate audit trail for auditor activities
  • Automatic expiration enforced at API level

Compliance Integration​

This workflow supports:

  • SOC 2 Type II: Evidence of access controls and audit logging
  • ISO 27001: Access management controls (A.9)
  • GDPR: Article 28 processor access documentation
  • HIPAA: Access control audit requirements

Troubleshooting​

Common Issue 1​

Problem: Description of issue Solution: Steps to resolve

Common Issue 2​

Problem: Description of issue Solution: Steps to resolve

Next Steps​

After completing this guide:

  1. Explore: Additional related features
  2. Practice: Apply concepts in your project
  3. Reference: Related documentation