Integrations API

The Integrations API connects projects to external services through four resources. REST, GraphQL, and MCP use the same resource names. The SDK covers integrations, connections, and integration tools. It has no project integration methods.

ResourceWhat it is
IntegrationA catalog entry for one external service, such as gmail.
Project integrationThe settings of one project for one integration.
ConnectionAn authorized account for an integration. It holds provider access, not settings.
Integration toolOne provider operation. Its qualified name is <integration>__<tool>, for example gmail__list_emails.

Integrations

The catalog is the same for every project. The integration catalog lists each integration with its authentication model, credential variables, and tools.

Experimental integrations need VERYFRONT_EXPERIMENTAL_INTEGRATIONS in the project environment. Set it to all or to a comma-separated list of integration names.

Project integrations

A project integration stores how one project uses one integration:

  • allowed_tools: The tools that agent runs and mock mode can use. null allows every tool.
  • config: Integration-specific settings that match config_schema.
  • execution_mode: real calls the provider. mock runs the mock tools of the integration, for tests.
  • scope: project uses one shared connection. user uses the personal connection of each user.

PATCH /projects/{project_reference}/integrations/{name} changes only the fields you send. Send scope in the first update. Without it, the API stores project scope.

bash
curl --fail-with-body -X PATCH \
  "https://api.veryfront.com/projects/support-assistant/integrations/gmail" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"project","allowed_tools":["list_emails"]}'

DELETE on the same path resets the settings to the defaults. It does not remove connections.

allowed_tools does not limit a direct run in real mode. There, the project permission of the credential decides: project.integrations.read, or project.integrations.connect for a tool that writes.

Connections

A connection authorizes one provider account. A project connection is shared. A user connection belongs to the person who authorized it. Project access does not grant access to another user's private connection.

The credential decides which connections a request sees:

  • API key or service account: Shared project connections only.
  • Signed-in user: Their own private connections and the shared project connections.

GET /projects/{project_reference}/connections lists the connections of one project. GET /connections lists the connections of the signed-in user across projects. It rejects an API key with 401.

Each connection has a connection_generation_id. It changes when the account behind the connection is replaced.

Attaching a tool to an agent does not supply a connection. Source-defined agent capabilities belong to the Agents API.

Authentication models

The provider decides how access is established. This authorization is separate from the Veryfront credentials in Authentication and access.

ModelSource of provider access
OAuth 2.0A user authorizes access on the consent screen of the provider. Supported refresh flows renew tokens.
OAuth client credentialsProject credentials get machine-to-machine tokens without a user redirect.
API keyA project environment variable supplies a key.
Basic authProject environment variables supply a username and password. Some providers use an API key as the username.

Managed and custom OAuth apps

A managed OAuth app lets users connect without a provider app of your own. Custom OAuth credentials take precedence, in this order: project integration credentials, project environment variables, then the managed app.

Use a custom app for consent branding, provider verification, or extra scopes. A failed connection can come from a callback URL, scope, or permission problem. The returned error identifies what to check.

Run an integration tool

  1. List the tools: Read the selected tool's input schema.
  2. Select a connection: Keep its id and connection_generation_id.
  3. Check readiness: Stop when the tool is blocked.
  4. Run the tool: Send the arguments and the selected connection.

The examples send an API key, so they use a shared project connection. For a user scope integration, send the token of the user who owns the connection. With an API key, readiness reports a missing connection.

Write tools change external state. Start with a read-only tool.

List the tools

GET /integration-tools lists the tools the credential can run, with their input schemas. The integration tool routes take the project from the credential. If the credential is not bound to one project, send x-veryfront-project-slug.

bash
curl --fail-with-body "https://api.veryfront.com/integration-tools?integration=gmail" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "x-veryfront-project-slug: support-assistant"

Check readiness

Readiness checks stored metadata without contacting the provider. It reports eligible, blocked, or unknown. A blocked result is a response, not an error.

bash
curl --fail-with-body -G \
  "https://api.veryfront.com/projects/support-assistant/integrations/gmail/readiness" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  --data-urlencode "tool_name=gmail__list_emails" \
  --data-urlencode "connection_id=<CONNECTION_ID>"

Read local_eligibility.state:

  • blocked: The tool cannot run. local_eligibility.blockers lists the reasons.
  • eligible: A connected OAuth connection is selected.
  • unknown: Stored metadata cannot decide. This is normal for project credentials and for mock mode. Run the tool to get the result.

The readiness check refuses a run token or a service account with 403. With those credentials, skip it and run the tool.

Run the tool

POST /integration-tools/{tool_name}/run runs the tool synchronously. Put the provider arguments in arguments. expected_connection_generation_id rejects the run with 409 if the account was replaced.

bash
curl --fail-with-body -X POST \
  "https://api.veryfront.com/integration-tools/gmail__list_emails/run" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "x-veryfront-project-slug: support-assistant" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {"q": "in:inbox", "maxResults": 1},
    "connection_id": "<CONNECTION_ID>",
    "expected_connection_generation_id": "<CONNECTION_GENERATION_ID>"
  }'

The response is the tool result. A provider failure returns 200 with isError: true. Invalid arguments that fail a declared body input schema return 400 before the tool operation is sent. Authentication and scope checks may contact the provider first.

If a call is denied, check readiness when your credential supports it. Then check the credential's project permissions and the account's provider permissions. For an agent run or mock mode, also check allowed_tools.

SDK, GraphQL, and MCP

The SDK client runs the same flow:

ts
import { createIntegrationClient } from "veryfront/integrations";

const client = await createIntegrationClient({
  apiBaseUrl: "https://api.veryfront.com",
  authToken: "<TOKEN>",
  projectReference: "support-assistant",
});

const selection = {
  connectionId: "<CONNECTION_ID>",
  expectedConnectionGenerationId: "<CONNECTION_GENERATION_ID>",
};

const readiness = await client.readiness("gmail__list_emails", selection);
if (readiness.local_eligibility.state === "blocked") {
  throw new Error(`Not ready: ${readiness.local_eligibility.blockers.join(", ")}`);
}

const outcome = await client.call(
  "gmail__list_emails",
  { q: "in:inbox", maxResults: 1 },
  selection,
);
console.log(outcome.status);

GraphQL uses the integrationTools and integrationReadiness queries and the runIntegrationTool mutation. MCP uses veryfront__check_integration_readiness and the native tools/list and tools/call requests.

MCP lists and runs integration tools only on a project-bound request. Use a project-scoped API key or the /projects/{project_reference}/mcp endpoint. MCP does not read x-veryfront-project-slug. Pass the connection in _meta:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gmail__list_emails",
    "arguments": {"q": "in:inbox", "maxResults": 1},
    "_meta": {
      "connection_id": "<CONNECTION_ID>",
      "expected_connection_generation_id": "<CONNECTION_GENERATION_ID>"
    }
  }
}

Connections also support external storage and messaging:

  • External files: Browse and manage the files in a user's own OneDrive, SharePoint, or Google Drive. An import creates a project upload. It does not index the file for knowledge retrieval.
  • Channels: Connect a messaging platform to a project agent.

Get started

Connect an integration explains project setup and verification. Set up Salesforce covers Salesforce-specific authorization.

API references