Integrations API

Connect third-party cloud providers, identity platforms, DevOps tools, and more. Automatically collect compliance evidence and run control tests against connected services. All endpoints require JWT authentication.

List Integrations

GET /api/v1/integrations 🔒

List all available integrations with the current account's connection status, last sync time, and evidence count.

Query Parameters

Param	Type	Description
`category`	string	Filter: `cloud`, `identity`, `devops`, `hr`, `communication`, `monitoring`

# cURL
curl https://api.privabase.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by category
curl "https://api.privabase.com/api/v1/integrations?category=cloud" \
  -H "Authorization: Bearer YOUR_TOKEN"

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/integrations', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const { integrations } = await res.json();

# Python
import requests
resp = requests.get('https://api.privabase.com/api/v1/integrations',
    headers={'Authorization': 'Bearer YOUR_TOKEN'})
integrations = resp.json()['integrations']

Response

{
  "success": true,
  "integrations": [
    {
      "id": "aws",
      "name": "Amazon Web Services",
      "icon": "aws",
      "category": "cloud",
      "authType": "api_key",
      "connected": true,
      "status": "active",
      "lastSync": "2026-03-14T10:30:00Z"
    },
    {
      "id": "okta",
      "name": "Okta",
      "icon": "okta",
      "category": "identity",
      "authType": "oauth2",
      "connected": false,
      "status": null,
      "lastSync": null
    }
  ]
}

Connect an Integration

POST /api/v1/integrations/:id/connect 🔒

Initiate OAuth flow or store API key/service account credentials for an integration.

Request Body

Field	Type	Required	Description
`credentials`	object	Yes	OAuth tokens, API key, or service account credentials
`sync_frequency`	string	No	`hourly`, `daily` (default), or `weekly`

curl -X POST https://api.privabase.com/api/v1/integrations/aws/connect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "access_key_id": "AKIA...",
      "secret_access_key": "wJalr..."
    },
    "sync_frequency": "daily"
  }'

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/integrations/aws/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    credentials: { access_key_id: 'AKIA...', secret_access_key: 'wJalr...' },
    sync_frequency: 'daily'
  })
});

# Python
resp = requests.post('https://api.privabase.com/api/v1/integrations/aws/connect',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'credentials': {'access_key_id': 'AKIA...', 'secret_access_key': 'wJalr...'},
        'sync_frequency': 'daily'
    })

Response

{
  "success": true,
  "connectionId": "conn-abc-123",
  "metadata": {
    "accountAlias": "my-aws-account",
    "regions": ["us-east-1", "eu-west-1"]
  }
}

Trigger Manual Sync

POST /api/v1/integrations/:id/sync 🔒

Immediately run evidence collection and control tests for a connected integration.

curl -X POST https://api.privabase.com/api/v1/integrations/aws/sync \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "evidenceCount": 47,
  "errors": [],
  "duration": 12340
}

Disconnect an Integration

DELETE /api/v1/integrations/:id/disconnect 🔒

Revoke access and remove stored credentials for an integration.

curl -X DELETE https://api.privabase.com/api/v1/integrations/aws/disconnect \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "message": "Integration disconnected"
}

List Collected Evidence

GET /api/v1/integrations/:id/evidence 🔒

Returns all evidence items collected during the last sync for a connected integration.

Query Parameters

Param	Type	Description
`limit`	integer	Max results (default 50, max 200)
`offset`	integer	Pagination offset (default 0)

curl "https://api.privabase.com/api/v1/integrations/aws/evidence?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "evidence": [
    {
      "id": "ev-001",
      "control_id": "soc2-cc6.1",
      "framework_id": "soc2",
      "type": "config_check",
      "status": "passing",
      "title": "S3 bucket encryption enabled",
      "collected_at": "2026-03-14T10:30:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Control Test Results

GET /api/v1/integrations/:id/controls 🔒

Returns the status of each mapped compliance control based on collected evidence.

curl https://api.privabase.com/api/v1/integrations/aws/controls \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "connected": true,
  "controlMappings": [
    {
      "controlId": "soc2-cc6.1",
      "frameworkId": "soc2",
      "controlName": "Logical and Physical Access Controls"
    }
  ],
  "controlResults": [
    {
      "controlId": "soc2-cc6.1",
      "frameworkId": "soc2",
      "controlName": "Logical and Physical Access Controls",
      "status": "passing",
      "passing": 12,
      "total": 12
    }
  ]
}

Integration Status

GET /api/v1/integrations/:id/status 🔒

Get connection status with sync history for an integration.

curl https://api.privabase.com/api/v1/integrations/aws/status \
  -H "Authorization: Bearer YOUR_TOKEN"

OAuth Authorization URL

GET /api/v1/integrations/:id/oauth-url 🔒

Returns the OAuth2 authorization URL to redirect the user to for connecting OAuth-based integrations (e.g., GitHub, Okta).

curl https://api.privabase.com/api/v1/integrations/github/oauth-url \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "authUrl": "https://github.com/login/oauth/authorize?client_id=...&scope=...&state=..."
}

OAuth Callback

GET /api/v1/integrations/callback

Handles OAuth2 authorization code callback from integration providers. Redirects to dashboard after successful connection. No authentication required — uses encoded state parameter.

Query Parameters

Param	Type	Required	Description
`code`	string	Yes	Authorization code from provider
`state`	string	Yes	Base64-encoded JSON with integrationId and accountId