API Keys & Integrations

Connecting Dictiva to Your Workflow

As governance programs mature, they need to connect with other systems — GRC platforms, ticketing tools, CI/CD pipelines, and internal dashboards. Dictiva's REST API lets you read and write governance data programmatically using API keys.

API access requires the Professional plan (read-only) or Business plan (read and write). See Billing & Plans for details.

Creating an API Key

1. Navigate to Settings > API Keys
2. Click Create API Key
3. Give it a descriptive name (e.g., "CI/CD Pipeline" or "Jira Integration")
4. Select the scope: Read or Read + Write
5. Click Create
6. Copy the key immediately — it is only shown once

API keys are scoped to your tenant. They can access all resources within your workspace but cannot access other tenants' data.

Authentication

All API requests use Bearer token authentication. Include your API key in the Authorization header:

curl -H "Authorization: Bearer dv_live_abc123..." \
     https://app.dictiva.com/api/v1/statements

API Versioning

The API uses path-based versioning. All endpoints are available under /api/v1/:

GET  /api/v1/statements
GET  /api/v1/statements/:id
GET  /api/v1/assemblies
GET  /api/v1/glossary

The /api/v1/* prefix is rewritten internally to the unversioned handlers — this ensures backward compatibility as the API evolves.

Common API Operations

List Statements

curl -H "Authorization: Bearer dv_live_abc123..." \
     https://app.dictiva.com/api/v1/statements

Returns a paginated list of your tenant's governance statements with metadata including status, domain, maturity level, and version history.

Get a Single Statement

curl -H "Authorization: Bearer dv_live_abc123..." \
     https://app.dictiva.com/api/v1/statements/550e8400-e29b-41d4-a716-446655440000

List Policies & Standards

curl -H "Authorization: Bearer dv_live_abc123..." \
     https://app.dictiva.com/api/v1/assemblies

JavaScript Example

const response = await fetch(
  "https://app.dictiva.com/api/v1/statements",
  {
    headers: {
      Authorization: "Bearer dv_live_abc123...",
      "Content-Type": "application/json",
    },
  }
);
const data = await response.json();

Rate Limits

API requests are rate-limited per API key using a fixed 60-second window. Limits vary by plan:

Every API response includes rate limit headers:

• X-RateLimit-Limit — maximum requests per window
• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• X-RateLimit-Window — window duration in seconds (60)

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header. Session-based (browser) requests are exempt from rate limiting.

Handling 429 Responses

# Example 429 response
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1742342460
Retry-After: 42

{"error": "Rate limit exceeded", "retryAfter": 42}

Implement exponential backoff: wait for the Retry-After value, then retry with increasing delays.

MCP & Agent Access

Dictiva also exposes agent-specific endpoints and a Model Context Protocol (MCP) server for AI assistants. MCP access requires the Business or Enterprise plan.

See the MCP Governance Server Guide for agent endpoints, available tools, setup instructions, and configuration.

API Usage Dashboard

Monitor your API and MCP request volume in Settings > Billing > API & MCP Usage. The dashboard shows:

• Current-period request totals (API and MCP separately)
• Rate limit utilization with upgrade prompt at >80%
• 30-day daily trend chart

Interactive API Documentation

Dictiva provides interactive API documentation powered by Scalar UI:

• URL: app.dictiva.com/api/docs
• Features: Try-it-now request builder, multi-language code samples, full request/response schemas
• Spec: The OpenAPI 3.1 specification is available at /api/openapi.json

The interactive docs let you test API calls directly from your browser using your API key.

Security Best Practices

• Never commit API keys to version control. Use environment variables or a secrets manager.
• Use separate keys for each integration. If one is compromised, you can revoke it without disrupting others.
• Prefer read-only keys when possible. Only create read+write keys when the integration needs to modify data.
• Rotate keys periodically. Delete old keys and create new ones on a regular schedule.
• Monitor usage in the audit log. API operations appear in the tenant audit trail alongside user actions.

Revoking an API Key

If a key is compromised or no longer needed:

1. Go to Settings > API Keys
2. Find the key by name
3. Click Revoke
4. Confirm the deletion

Revocation is immediate. Any requests using the revoked key will receive 401 Unauthorized.

Next Steps

• Explore the interactive API docs to see all available endpoints
• Set up user roles to control who can create API keys
• Review your plan to ensure API access is enabled