Skip to content
TruthVouch Docs

Platform API Reference

The Platform API provides endpoints for managing organizations, users, roles, invitations, billing, and subscriptions.

Authentication

All Platform API endpoints require Bearer token authentication:

Terminal window
curl https://api.truthvouch.io/v1/organizations \
  -H "Authorization: Bearer token_abc123..."

Get token:

  1. Log into TruthVouch dashboard
  2. Settings → API Keys
  3. Create new key
  4. Use token in Authorization header

Organizations

List Organizations

GET /v1/organizations HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "organizations": [
    {
      "id": "org-abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "created_at": "2023-01-15T10:00:00Z",
      "plan": "enterprise",
      "members_count": 45,
      "gateway_instances": 3,
      "sentinel_agents": 200
    }
  ],
  "total": 1
}

Get Organization Details

GET /v1/organizations/{org_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "id": "org-abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "description": "Manufacturing company",
  "website": "https://acme.com",
  "created_at": "2023-01-15T10:00:00Z",
  "timezone": "America/New_York",
  "settings": {
    "sso_enabled": true,
    "sso_provider": "okta",
    "ip_allowlist": ["203.0.113.0/24"],
    "data_residency": "us"
  },
  "plan": "enterprise",
  "members_count": 45,
  "gateway_instances": 3,
  "sentinel_agents": 200
}

Update Organization

PATCH /v1/organizations/{org_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...
Content-Type: application/json


{
  "name": "Acme Corporation",
  "timezone": "America/Los_Angeles",
  "settings": {
    "ip_allowlist": ["203.0.113.0/24", "198.51.100.0/24"]
  }
}

Users

List Organization Members

GET /v1/organizations/{org_id}/members HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "members": [
    {
      "id": "user-abc123",
      "email": "alice@acme.com",
      "name": "Alice Johnson",
      "role": "admin",
      "status": "active",
      "created_at": "2023-01-15T10:00:00Z",
      "last_login": "2024-01-15T14:30:00Z",
      "mfa_enabled": true
    }
  ],
  "total": 45
}

Add Organization Member

POST /v1/organizations/{org_id}/members HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...
Content-Type: application/json


{
  "email": "bob@acme.com",
  "name": "Bob Smith",
  "role": "member"
}

Response:

{
  "id": "user-def456",
  "email": "bob@acme.com",
  "name": "Bob Smith",
  "role": "member",
  "status": "pending_invite",
  "invitation_sent_at": "2024-01-15T15:00:00Z"
}

Update Member Role

PATCH /v1/organizations/{org_id}/members/{user_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...
Content-Type: application/json


{
  "role": "editor"
}

Remove Member

DELETE /v1/organizations/{org_id}/members/{user_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Roles

Available roles:

RolePermissions
ownerFull access, billing management, organization deletion
adminManage members, policies, settings, dashboards
editorManage policies, view dashboards, manage alerts
memberView dashboards, manage own settings
viewerRead-only access to dashboards

Get Roles

GET /v1/roles HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Invitations

List Pending Invitations

GET /v1/organizations/{org_id}/invitations HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "invitations": [
    {
      "id": "inv-abc123",
      "email": "charlie@acme.com",
      "role": "editor",
      "sent_at": "2024-01-15T10:00:00Z",
      "expires_at": "2024-02-15T10:00:00Z",
      "status": "pending"
    }
  ],
  "total": 3
}

Resend Invitation

POST /v1/organizations/{org_id}/invitations/{invitation_id}/resend HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Revoke Invitation

DELETE /v1/organizations/{org_id}/invitations/{invitation_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Billing

Get Subscription

GET /v1/organizations/{org_id}/subscription HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "id": "sub-abc123",
  "organization_id": "org-abc123",
  "plan": "enterprise",
  "status": "active",
  "billing_cycle_start": "2024-01-01T00:00:00Z",
  "billing_cycle_end": "2024-02-01T00:00:00Z",
  "amount": 5000,
  "currency": "usd",
  "billing_email": "billing@acme.com",
  "auto_renew": true,
  "features": {
    "gateway_instances": 10,
    "sentinel_agents": 500,
    "api_requests_per_month": 1000000,
    "advanced_analytics": true,
    "custom_integrations": true
  }
}

Update Subscription

PATCH /v1/organizations/{org_id}/subscription HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...
Content-Type: application/json


{
  "plan": "business",
  "auto_renew": true
}

List Invoices

GET /v1/organizations/{org_id}/invoices HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "invoices": [
    {
      "id": "inv-202401",
      "amount": 5000,
      "currency": "usd",
      "date": "2024-01-01",
      "due_date": "2024-01-30",
      "status": "paid",
      "pdf_url": "https://..."
    }
  ],
  "total": 12
}

Usage and Quotas

Get Usage

GET /v1/organizations/{org_id}/usage HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "gateway_instances": {
    "limit": 10,
    "used": 3
  },
  "sentinel_agents": {
    "limit": 500,
    "used": 200
  },
  "api_requests": {
    "limit": 1000000,
    "used": 450000
  },
  "gateway_scans": {
    "limit": 10000000,
    "used": 5600000
  },
  "storage_gb": {
    "limit": 1000,
    "used": 234
  }
}

API Keys

List API Keys

GET /v1/organizations/{org_id}/api-keys HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Response:

{
  "api_keys": [
    {
      "id": "key-abc123",
      "name": "Production API Key",
      "prefix": "token_abc123...",
      "created_at": "2024-01-15T10:00:00Z",
      "last_used": "2024-01-15T14:30:00Z",
      "expires_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 5
}

Create API Key

POST /v1/organizations/{org_id}/api-keys HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...
Content-Type: application/json


{
  "name": "Staging API Key",
  "expires_in_days": 365
}

Response:

{
  "id": "key-def456",
  "name": "Staging API Key",
  "token": "token_def456_full_token_here",
  "expires_at": "2025-01-15T10:00:00Z"
}

Note: Token is only returned once at creation. Store securely.

Revoke API Key

DELETE /v1/organizations/{org_id}/api-keys/{key_id} HTTP/1.1
Host: api.truthvouch.io
Authorization: Bearer token_abc123...

Error Handling

Error Response Format

{
  "error": "invalid_request",
  "message": "Organization not found",
  "code": 404
}

Common Error Codes

CodeMeaning
400Bad Request
401Unauthorized (invalid token)
403Forbidden (insufficient permissions)
404Not Found
429Rate Limited
500Server Error

Rate Limiting

Rate limit: 100 requests per minute per API key


Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705314600

When rate limited (429):

Retry-After: 60

Pagination

List endpoints support pagination:

GET /v1/organizations?limit=20&offset=40 HTTP/1.1

Response:

{
  "organizations": [...],
  "total": 150,
  "limit": 20,
  "offset": 40,
  "has_more": true
}

Example: Complete User Invite Flow

import requests


api_key = "token_abc123..."
org_id = "org-abc123"
headers = {"Authorization": f"Bearer {api_key}"}


# 1. Invite user
response = requests.post(
    f"https://api.truthvouch.io/v1/organizations/{org_id}/members",
    json={
        "email": "newuser@company.com",
        "name": "New User",
        "role": "editor"
    },
    headers=headers
)
print(f"User invited: {response.json()['id']}")


# 2. List pending invitations
response = requests.get(
    f"https://api.truthvouch.io/v1/organizations/{org_id}/invitations",
    headers=headers
)
pending = [i for i in response.json()['invitations'] if i['status'] == 'pending']
print(f"Pending invitations: {len(pending)}")


# 3. Get updated member count
response = requests.get(
    f"https://api.truthvouch.io/v1/organizations/{org_id}",
    headers=headers
)
print(f"Organization members: {response.json()['members_count']}")

See Pagination for detailed pagination patterns.