Integrations API

The Integrations API gives a project access to external services. It has four resources. Each resource has the same name in REST, GraphQL, and MCP. The SDK covers integrations, connections, and integration tools. It has no project integration methods.

Resource	What it is
Integration	A catalog entry for one external service, such as `gmail`.
Project integration	The settings of one project for one integration.
Connection	An authorized account for an integration. It holds provider access, not settings.
Integration tool	One 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.

update-project-integration.sh

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 is one authorized account. A project scope connection is shared by the project. A user scope connection is private to the user who authorized it. Access to a project does not grant access to the private connection of another user. 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.

Model	Source of provider access
OAuth 2.0	A user authorizes access on the consent screen of the provider. Supported refresh flows renew tokens.
OAuth client credentials	Project credentials get machine-to-machine tokens without a user redirect.
API key	A project environment variable supplies a key.
Basic auth	Project 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

Run a tool in four steps:

List the tools: Read the input schema of the tool.
Select a connection: Keep its id and connection_generation_id.
Check readiness: Stop when the tool is blocked.
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.

list-integration-tools.sh

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 tells you whether a tool can run now. It reads stored metadata only and does not contact the provider. A blocked result is a response, not an error.

check-integration-readiness.sh

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.

run-integration-tool.sh

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. When a run is denied, check readiness first. Then check the project permission of the credential and the provider permissions of the account. For an agent run or mock mode, also check allowed_tools.

SDK, GraphQL, and MCP

The SDK client runs the same flow:

run-integration-tool.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:

run-integration-tool.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>"
    }
  }
}

External storage and channels use connections. They have their own operations:

External storage: Browse and manage files in an external storage provider.
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.

Get started

APIs

REST API

GraphQL API

MCP API

Integrations

Project integrations

Connections

Authentication models

Managed and custom OAuth apps

Run an integration tool

List the tools

Check readiness

Run the tool

SDK, GraphQL, and MCP

Get started

API references

​Integrations

​Project integrations

​Connections

​Authentication models

​Managed and custom OAuth apps

​Run an integration tool

​List the tools

​Check readiness

​Run the tool

​SDK, GraphQL, and MCP

​Related resources

​Get started

​API references

Integrations

Project integrations

Connections

Authentication models

Managed and custom OAuth apps

Run an integration tool

List the tools

Check readiness

Run the tool

SDK, GraphQL, and MCP

Related resources

Get started

API references