Documentation · Quick start

Build with CaptivaHQ

A concise guide to the application, REST API, and Model Context Protocol (MCP). Access is workspace-specific and every integration is limited by the permissions granted to it.

Application basics

CaptivaHQ brings CRM, projects, inventory, billing, service, automation, and other business workflows into one permissioned workspace. The modules visible to you depend on your organization’s configuration and your assigned access group.

Get started

  1. Accept your workspace invitation and sign in using the method configured by your administrator.
  2. Open Home to review assigned work, recent activity, and notifications.
  3. Use the module navigation to find records such as accounts, leads, deals, projects, tasks, and invoices.
  4. Ask your workspace administrator when a module or action is not visible; access is intentionally permission-based.

Connect an MCP client

MCP lets compatible AI clients discover and call CaptivaHQ tools. The available tool list is filtered to the integration’s scopes, enabled modules, and effective workspace permissions.

  1. Ask a workspace owner or administrator to create an OAuth application with only the scopes your integration needs.
  2. Copy the client ID and one-time client secret into your secret manager. Never place either value in source control or browser code.
  3. Exchange those credentials for a short-lived access token.
  4. Configure your MCP client with your workspace host and the endpoint /api/v1/mcp.
  5. Initialize the connection, list tools, then call only tools returned for that token.
{
  "mcpServers": {
    "captivahq": {
      "url": "https://<workspace-host>/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <access-token>"
      }
    }
  }
}

Access tokens expire. Refresh them through the OAuth flow supported by your workspace, and rotate the client secret immediately if it may have been exposed.

Use the REST API

The versioned REST API uses JSON and bearer authentication. Resource routes generally follow /api/v1/<module>/<resource>. List endpoints are paginated and write operations may support an idempotency key.

1. Request an access token

curl -X POST "https://<workspace-host>/api/v1/public/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

2. Call an endpoint

curl "https://<workspace-host>/api/v1/crm/leads?limit=25" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

Use the correlation ID returned with a failed request when contacting support. A 401 means authentication failed, 403 means the token lacks permission, 429 means the caller should retry later, and unexpected errors return a redacted message.

Security checklist

  • Grant the smallest practical set of scopes and review them periodically.
  • Keep client secrets and tokens in a secret manager; never log or publish them.
  • Use HTTPS for every request and validate webhook signatures when receiving events.
  • Do not embed machine credentials in websites, mobile applications, or shared MCP configuration files.
  • Revoke and recreate an integration when credentials are lost or an operator no longer needs access.

Machine-readable resources

OpenAPI contractCurrent API schema in JSON MCP manifestCurrent platform tool catalog

These catalogs describe the platform surface. The routes and tools available to a specific integration are still determined by its workspace, modules, and permissions.