Build on Vouli IQ

Writes and management

External systems can push data in. Each operation needs its own scope — read:all never grants a write: or manage: scope, nor read:audit or the scopes added since (such as read:metrics), which are granted by name — and the plan that includes the module (otherwise 403 feature_not_in_plan). A write key acts for your organisation with contributor-level rights; webhook management and the audit export are admin-level. Every write runs through the same rules as the app (an unevidenced severity downgrade is refused, a KPI actual follows its latest period) and is recorded in your audit log as api.write.<resource> with the key that made it.

• Bodies are JSON and strict: an unknown field is a 400 unknown_field; org_id or any user-id or authorship field is a 400 forbidden_field. The organisation is always the key's.
• An id from another organisation is a 404, exactly like an id that does not exist.
• Records cannot be deleted through the API (except webhook endpoints); deletion stays in the app.
• POST /kpis/checkins takes up to 500 data points and is all or nothing: one bad point refuses the batch.
• Every list accepts updated_since (an ISO date or timestamp) for incremental sync.

Verifying a webhook: both SDKs ship verifyWebhookSignature (verify_webhook_signature in Python), generated from the code that signs deliveries. Pass the raw body, the request headers and your endpoint's secret: the timestamped X-Vouli-Signature-V2 is checked within a 300-second window, and requireV2 (require_v2) stops it falling back to the older X-Vouli-Signature. POST /webhooks/subscriptions/{id}/test sends a signed ping so you can prove it before going live.

Push events from your systems (Event API)

Create a push source in Dashboard → Grounding → Push sources (an administrator creates it, a different administrator approves it) and send up to 100 events — 500 metric points — per request to POST /api/v1/events. Pushed values reach the signal bus near-real-time (seconds after a push); a key with an approved metric definition also lands in that governed series. Included on the Max plan and above.

• Sign <Vouli-Timestamp>.<raw body> with HMAC-SHA256 and the source's secret; send Vouli-Source, Vouli-Timestamp (unix seconds, within ±5 minutes) and Vouli-Signature: v1=<hex>. Each signature is accepted once: sign every retry afresh.
• Or, for a source that allows keys, send an API key holding write:events with Vouli-Source.
• An Idempotency-Key is required. An event whose external_id and type the source sent before is counted as a duplicate, not written twice.
• org_id and source are refused anywhere in the body. Strings are neutralised before storage; do not send personal data.
• The source's secret can be rotated: the previous one keeps working for 24 hours.

BODY='{"events":[{"type":"finance.month_closed","occurred_at":"2026-10-01T00:00:00Z","external_id":"close-2026-09","metrics":[{"key":"finance.cash_usd","value":1250000,"unit":"USD"}]}]}'
T=$(date +%s)
SIG=$(printf '%s' "$T.$BODY" | openssl dgst -sha256 -hmac "$VOULI_PUSH_SECRET" | sed 's/^.* //')
curl -X POST https://www.vouliiq.com/api/v1/events \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -H "Vouli-Source: $VOULI_SOURCE_ID" -H "Vouli-Timestamp: $T" -H "Vouli-Signature: v1=$SIG" \
  --data "$BODY"

// TypeScript
import { signEventRequest } from '@vouli-iq/sdk';
const headers = await signEventRequest(body, secret);   // Vouli-Timestamp + Vouli-Signature

# Python
from vouli_iq import sign_event_request
headers = sign_event_request(body, secret)

Connect AI assistants (MCP)

Vouli IQ is also a Model Context Protocol server. Connect Claude, ChatGPT, Copilot or any other MCP client with an API key, and the assistant can answer questions from your organisation's governance data — the same resources as the REST API, with the same scopes, rate limit and sandbox. Every tool is read-only. Included on the Max plan and above.

Endpoint

https://www.vouliiq.com/api/v1/mcp

Transport

Streamable HTTP with JSON responses; protocol versions 2025-06-18, 2025-03-26, 2024-11-05. Authenticate with Authorization: Bearer vk_live_….

Claude Code

claude mcp add --transport http vouli-iq https://www.vouliiq.com/api/v1/mcp \
  --header "Authorization: Bearer $VOULI_API_KEY"

Claude Desktop

Claude Desktop starts local servers from claude_desktop_config.json. The open-source mcp-remote package (needs Node.js) bridges it to this endpoint and sends your key as a header:

{
  "mcpServers": {
"vouli-iq": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://www.vouliiq.com/api/v1/mcp",
           "--header", "Authorization:${VOULI_AUTH}"],
  "env": { "VOULI_AUTH": "Bearer vk_live_XXXXXXXX_your_secret" }
}
  }
}

Any other MCP client

Give the client the endpoint URL and the key as a request header. Most clients that speak Streamable HTTP take a configuration of this shape:

{
  "mcpServers": {
"vouli-iq": {
  "type": "http",
  "url": "https://www.vouliiq.com/api/v1/mcp",
  "headers": { "Authorization": "Bearer vk_live_XXXXXXXX_your_secret" }
}
  }
}

# Or check the handshake by hand:
curl https://www.vouliiq.com/api/v1/mcp \
  -H "Authorization: Bearer $VOULI_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools

• Read-only by design: each tool reads one resource and nothing else. None creates, changes or deletes anything in Vouli IQ.
• Your organisation only: results always belong to the organisation that owns the key, and no tool argument can select another one.
• Scopes: a tool needs its resource's scope (or read:all). Without it the tool answers This API key does not have the read:risks scope. Mint a dedicated key for each assistant with only the scopes it needs, and revoke it when you disconnect.
• Sandbox: a vk_test_… key returns the same [SANDBOX] sample rows as the REST sandbox and never your data.
• Rate limit: every tool call spends one request from the key's API rate limit. Connection set-up messages are limited separately.
• The server tells the assistant to treat field values as your records, not as instructions to follow.

Connecting your own MCP server to Vouli IQ

The other direction: Live Data Grounding reads figures from an MCP server you run. What your server must support today:

• A public HTTPS address (private and reserved addresses are refused, including after a redirect) speaking MCP Streamable HTTP. Vouli IQ sends initialize with protocol version 2025-06-18 and accepts 2025-06-18, 2025-03-26, 2024-11-05; it keeps the Mcp-Session-Id you assign and reads JSON or SSE replies (up to 5 MB each). A server that answers only bare JSON-RPC still works.
• Authentication: an API token, sent as Authorization: Bearer …. OAuth 2.1, client credentials and mutual TLS are coming soon and are refused at registration until then — never quietly replaced by a token.
• Read-only tools (readOnlyHint: true, or a read-style name). Write tools are never called. tools/list pagination is followed up to 20 pages or 1,000 tools; a tool result with isError: true is treated as a failure, never as data.
• Nothing reaches an AI model unless an admin turns on “Use in AI” for the connection; values then enter briefs as quoted data with their source and age. Synced near-real-time: every 30–90 minutes, or on demand.

Build apps for other organisations (OAuth 2.0)

Partner apps connect with OAuth 2.0 using the authorization code flow with PKCE: an organisation admin approves exactly the scopes shown on the consent screen, and can disconnect the app at any time in Settings → Connected apps. An API key is for your own organisation's integrations; an app that other organisations connect uses OAuth, so nobody ever pastes a key into it.

1. Register the app in the developer console (sign in; an organisation admin registers). Give its redirect URIs — https, or http://localhost while you develop — and the scopes it needs. The client secret is shown once and can be rotated.
2. Send the admin to the authorization endpoint with response_type=code, your client_id, an exact registered redirect_uri, the scope, a state and a PKCE code_challenge with code_challenge_method=S256. The consent screen names your app, your organisation as its publisher, each scope in plain language and the organisation it would act on. Only an admin can approve.
3. Exchange the code within 60 seconds at the token endpoint, authenticating with your client secret (HTTP Basic or in the body) and sending the code_verifier. A code works once; presenting it again revokes the tokens it bought.
4. Call /api/v1 or the MCP server with Authorization: Bearer vou_at_…. Access tokens last 1 hour; refresh tokens last up to 30 days, work once and are replaced on every refresh. A refresh token used twice revokes the whole chain.
5. Live data needs the connecting organisation's plan to include the public API (Max and above).

curl https://www.vouliiq.com/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://your-app.example.com/callback" \
  -d code_verifier="$CODE_VERIFIER"

An admin sees every connected app, and disconnects it, in Settings → Connected apps; uninstalling the app from the marketplace revokes its tokens too. Revoke a token yourself with the revocation endpoint (revoking a refresh token revokes its access tokens).

Scopes for apps

The same scopes as API keys, checked by the same code. read:all never grants a write: or manage: scope, nor read:audit. A token can use only what the admin approved; if the admin later approves fewer scopes, tokens already issued lose the rest at once. This is the wording the consent screen shows.

Developer sandbox workspace

The developer console gives your organisation a free developer sandbox workspace: apps connected to it are served sample data, writes are simulated, and no paid plan is needed. Choose “Developer sandbox” on the consent screen and the token is served the same 42 sample rows test keys see — every human-readable value marked [SANDBOX], responses marked Vouli-Environment: test — and never any organisation's records, yours included. An app that has not been approved yet can already be connected by its own organisation, to the sandbox or to that organisation's own data.

Rate limits for apps

• Each connection (one app in one organisation) has its own limit at the organisation's plan rate, with the same X-RateLimit-* headers and 429 + Retry-After as a key. For OAuth tokens the limit is currently counted by each server instance, so treat the headers as the authority.
• Sandbox tokens: 60 requests a minute and 10,000 a day, whatever the plan.
• The token and revocation endpoints are limited per IP address; a 429 carries Retry-After.

App review

A new app is a Draft. When it is ready, submit it from the console: it becomes Submitted, then In review when a Vouli IQ reviewer takes it, and then Approved or Rejected — a rejection always carries the reviewer's reason, which you can read in the console. Only an approved app is listed in the marketplace catalogue and can be connected by other organisations. Approval records that a reviewer looked at what you submitted; it is not a certification or an endorsement, and nothing may describe it as one.

Partner programme

We are setting up a partner programme for technology partners, who build apps and integrations on the API, and services partners, who implement Vouli IQ or advise the boards that use it. If you are interested, tell us about yourself here; the details go to the Vouli IQ team.

Automation templates

Ready-made receivers for Vouli IQ webhooks. Each one checks X-Vouli-Signature (HMAC-SHA256 of the raw body with your subscription’s secret) before anything else, answers 401 when it does not match, and routes the 7 core event types to their own branches.

• n8n Download the workflow (JSON) — import it from Workflows, then set the signing secret.
• Make Download the scenario blueprint (JSON) — import it, turn on JSON pass-through and request headers on the webhook, paste the secret into both filters.
• Zapier Today: add a “Webhooks by Zapier” Catch Hook URL under Settings → Integrations. A Vouli IQ Zapier app definition exists but has not been published, so there is no public Vouli IQ Zapier app yet.

Actions: create and update records

The same packages can also write to Vouli IQ through the API v1 write endpoints: create or update a risk, create or update an incident, add a vendor, and record a KPI actual. Every call sends Authorization: Bearer, Vouli-Version and an Idempotency-Key derived from its input, so a retry is answered with the first response instead of writing twice. The key needs the matching scope: write:risks, write:incidents, write:vendor or write:kpis (read:all never grants one), and the plan must include that module.

• n8n Download the Jira to incident workflow (JSON) — a Jira issue becomes a Vouli IQ incident; import it into your own n8n.
• Make Download the actions blueprint (JSON) — one HTTP route per action; import it, then paste your API key and a relay token.
• Zapier The Vouli IQ Zapier app definition now also carries these six actions and three polling triggers built on updated_since, but it has not been published. Today, a “Webhooks by Zapier” Custom Request step can call the same endpoints with the headers above.

Identity provisioning (SCIM 2.0)

On the Enterprise plan, your identity provider — Okta, Microsoft Entra ID or any SCIM 2.0 client — can add, update and remove people in Vouli IQ automatically, and set each person's role from the directory groups they belong to.

Base URL

https://www.vouliiq.com/api/scim/v2

Authentication

Authorization: Bearer scim_… — a token a workspace administrator issues in Settings → Enterprise Access. It is shown once and is valid for one year.

• /Users and /Groups: create, read, update and replace; filtering and sorting; pages of up to 200 (default 100); version tags with If-Match; /Bulk of up to 100 operations. /ServiceProviderConfig lists exactly what is supported.
• Removing a person (DELETE, or setting active to false) takes them out of your organisation at once and cancels the API keys they created in it. If yours is the only organisation they belong to, their Vouli IQ sign-in is switched off too. Nothing is deleted: their record and the audit trail are kept, and setting active back to true restores their access and role.
• Details Vouli IQ does not keep — job title, phone numbers, addresses, and the enterprise fields such as department, employee number and manager — are accepted and set aside, so a directory's standard attribute mapping never causes an update to fail.

Roles from directory groups

A group's name decides the role it gives. When a person is in several matching groups, the most senior role wins. A group whose name contains none of the words below gives no role and changes no one's role. Administrator access is only ever given by a group whose name says so. Someone provisioned with no matching group starts as Viewer.