Connect an integration

Connect an external service to a project and verify a read-only operation before enabling writes.

Before you start

Choose a provider in the integration catalog and a project you can configure. Set a Veryfront API credential; provider credentials do not authenticate requests to Veryfront. Choose the provider access mode. Authorization code is the OAuth 2.0 grant for user-delegated access through a consent screen. Client credentials is the OAuth 2.0 grant for application/service access without a user consent redirect. A shared project connection can still be user-delegated; connection sharing and OAuth grant type are separate choices. API-key integrations use their listed environment variables. Outlook, OneDrive, SharePoint, Confluence, ServiceNow and Box also support hosted application access alongside delegated connections.

1. Check the integration

Call GET /integrations to inspect the catalog available to your credential:

list-integrations.sh

curl --fail-with-body https://api.veryfront.com/integrations \
  -H "Authorization: Bearer $VERYFRONT_API_KEY"

Check the provider’s credential requirements and available tools. Experimental integrations require VERYFRONT_EXPERIMENTAL_INTEGRATIONS in the project environment, set to all or selected integration names.

2. Authorize provider access

Choose the branch that matches the provider.

User-delegated OAuth connections

Create a one-time consent link with POST /projects/{project_reference}/integrations/{name}/connect-sessions. This example connects GitHub as a shared project connection:

create-connect-session.sh

curl --fail-with-body -X POST \
  "https://api.veryfront.com/projects/support-assistant/integrations/github/connect-sessions" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"project","redirect_uri":"https://veryfront.com"}' > connect-session.json

Open the returned connect_url in a browser before expires_at, then complete provider consent. Creating the link does not complete authorization. Custom return URLs must be allowed by the deployment. A project scope connection is shared by the project. It needs editor access to the project. The API key can then list it and run tools with it. A user scope connection is private to the user who authorized it. Create it and send every later request with that user’s token, not an API key.

Application client credentials and API keys

Set the variables named in the provider reference. For example, Stripe uses STRIPE_SECRET_KEY. Set ENVIRONMENT_ID to the environment where the integration executes, then call POST /projects/{project_reference}/environments/{environment_id}/variables:

set-provider-credential.sh

export ENVIRONMENT_ID="<ENVIRONMENT_ID>"

curl --fail-with-body -X POST \
  "https://api.veryfront.com/projects/support-assistant/environments/$ENVIRONMENT_ID/variables" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"STRIPE_SECRET_KEY","value":"<STRIPE_SECRET_KEY>"}'

Replace the secret placeholder before sending the request. Keep real credentials out of source control. For local development, use the project’s environment configuration described in the Code configuration guide.

3. Verify the connection

For OAuth, list the connections of the project with GET /projects/{project_reference}/connections:

list-project-connections.sh

curl --fail-with-body "https://api.veryfront.com/projects/support-assistant/connections?integration=github" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY"

Confirm the intended provider account is connected. The list returns 20 connections per page. If page_info.next is set, pass it as cursor to read the next page. An API key sees only shared project connections. For a user scope connection, send the token of the user who authorized it. Then run a read-only integration tool with arguments for resources the account can access. Run an integration tool shows how to check readiness and run it. Authorization does not choose the tools an agent can use. Set them in allowed_tools of the project integration. If a run fails, check the selected connection, the project integration, and the provider permissions. For credential-based integrations, also check the variable names and the runtime environment.

Application access

Outlook, OneDrive, SharePoint, Confluence, ServiceNow and Box support project application/service credentials alongside delegated OAuth connections. These methods are available through hosted integration tool execution; the installed framework’s local execution is a separate implementation. If your application decodes canonical control events, use an SDK release that supports these service identities.

1. Choose the access mode

Configure credentials as project environment variables, in the environment targeted by the run. Platform OAuth client variables such as MICROSOFT_CLIENT_ID configure delegated connection setup; they do not activate service mode. Without an explicit connection selector, nonempty variables in an integration’s _SERVICE_ACCOUNT_ namespace activate its application identity. Partial setup fails closed. Every integration has a separate namespace so configuring Outlook does not switch OneDrive or SharePoint. Complete setup must include every variable in its row below. For direct REST calls, an explicit connection_id selects the existing delegated connection even when these application credentials are configured. Include the observed expected_connection_generation_id when using optimistic connection selection. Runs retain the OAuth or service binding recorded at admission. A service-bound run fails if its credentials or policy are removed; it never falls back to a person’s OAuth token. Agent service runs, interactive or noninteractive, require project scope, an enabled project integration, permitted tools and the current project policy. Direct calls retain the API’s existing capability-based authorization and do not create a project tool policy implicitly. Application access is not permission to use every operation the provider offers.

2. Configure project variables

Every row requires <PREFIX>CLIENT_ID and <PREFIX>CLIENT_SECRET, plus its listed target variables. Target names below have the same prefix.

Integration	Prefix	Additional required variables	Token mechanism
Outlook	`OUTLOOK_SERVICE_ACCOUNT_`	`TENANT_ID`, `MAILBOX`	Microsoft client credentials
OneDrive	`ONEDRIVE_SERVICE_ACCOUNT_`	`TENANT_ID`, `DRIVE_ID`	Microsoft client credentials
SharePoint	`SHAREPOINT_SERVICE_ACCOUNT_`	`TENANT_ID`, `SITE_ID`	Microsoft client credentials
Confluence	`CONFLUENCE_SERVICE_ACCOUNT_`	`CLOUD_ID`	Atlassian service account client credentials
ServiceNow	`SERVICENOW_SERVICE_ACCOUNT_`	`INSTANCE`	Instance OAuth client credentials
Box	`BOX_SERVICE_ACCOUNT_`	`ENTERPRISE_ID`	Box enterprise-subject client credentials

Application tokens are acquired per execution, without a process token cache. Credential rotation and environment changes therefore affect subsequent requests immediately. Token requests use a timeout and reject redirects. Provider failures do not retry mutations or switch identities. Already-dispatched provider actions cannot be undone by removing a connection.

Microsoft

Register an application in the intended tenant, configure the application permissions needed by the selected tools and obtain administrator consent. Configure provider-side resource restrictions as appropriate. Requests use the tenant-specific token endpoint and https://graph.microsoft.com/.default; delegated scope names and offline_access do not belong in this token request. Outlook replaces /me with the configured mailbox under /users/{mailbox}. Shared-mailbox arguments, explicit message sender fields and schedule-query mailbox addresses must match that target. find_meeting_times requires delegated access and is rejected in application mode. OneDrive uses /drives/{driveId}. SharePoint requires a matching site target; list_sites is rejected in application mode because it enumerates outside that target. Use get_site with the configured site instead. Application permission support remains specific to each Graph operation, account type and tenant configuration.

Confluence

Create OAuth credentials for an Atlassian service account with Confluence scopes and access to the intended site/spaces. Calls use /ex/confluence/{cloudId}; a different tool cloudId is rejected. Space/page permissions remain enforced by Atlassian’s service account permissions. list_sites uses a delegated discovery endpoint and is rejected in service mode; use the configured cloud ID directly.

ServiceNow

Enable inbound client credentials on the target instance and configure an application user with appropriate roles and ACLs. INSTANCE is a host such as example.service-now.com, without a scheme; service mode accepts only standard service-now.com instance hosts. Delegated connections use SERVICENOW_CLIENT_ID, SERVICENOW_CLIENT_SECRET and SERVICENOW_INSTANCE, with the instance’s /oauth_auth.do and /oauth_token.do endpoints. The previous SERVICENOW_ACCESS_TOKEN plus SERVICENOW_INSTANCE configuration, including its accepted HTTPS URL and path-prefix normalization, remains usable as legacy bearer-token access when no service-account variables are set. Legacy SERVICENOW_API_BASE_URL overrides retain their previous host/path semantics and can supply the host without SERVICENOW_INSTANCE. These pasted tokens are not automatically renewed. Service-account variables take precedence over the legacy token unless a delegated connection is explicitly selected.

Box

Authorize a Box Server app using Client Credentials Grant for the enterprise. Token requests specify box_subject_type=enterprise and the configured enterprise ID. File/folder access follows that service account’s Box permissions; this implementation does not impersonate arbitrary managed users or add a folder-level restriction beyond provider permissions and selected tools. Delegated OAuth continues to use the existing Box OAuth application configuration.

Download response formats

Box download_file and application-mode OneDrive/SharePoint downloads return encoding: "base64", content_base64, content_type and decoded byte size. Decode content_base64 to recover the original file bytes. Existing delegated OneDrive/SharePoint downloads retain their original response format and limit. Application binary downloads are limited to 128 KiB so base64 results fit the persisted tool-event budget, including streamed responses without a declared length. Redirect destinations are validated against the outbound URL policy, credentials are removed across origins and redirect count/time are bounded. A provider 202 response returns pending status and retry timing instead of file content. Provider error responses retain ordinary status/error handling.

Verify access before enabling writes

Call a read-only tool against the configured resource in the target environment. Confirm that the returned mailbox, drive, site, instance or enterprise belongs to the intended account. Then verify one permitted write in a test resource before enabling writes for agents. Provider permissions and live credential exchanges require validation with your configured accounts. Use Run an integration tool for readiness and execution requests. Application identities use project credentials rather than the delegated connection inventory. An application credential alone does not grant an agent tool access.

Provider references

API references

Integrations REST endpoints, GraphQL operations, and MCP tools.
Integrations API: Integrations, project integrations, connections, and integration tools.

Get started

APIs

REST API

GraphQL API

MCP API

Connect an integration

Before you start

1. Check the integration

2. Authorize provider access

User-delegated OAuth connections

Application client credentials and API keys

3. Verify the connection

Application access

1. Choose the access mode

2. Configure project variables

Microsoft

Confluence

ServiceNow

Box

Download response formats

Verify access before enabling writes

Provider references

API references

​Before you start

​1. Check the integration

​2. Authorize provider access

​User-delegated OAuth connections

​Application client credentials and API keys

​3. Verify the connection

​Application access

​1. Choose the access mode

​2. Configure project variables

​Microsoft

​Confluence

​ServiceNow

​Box

​Download response formats

​Verify access before enabling writes

​Provider references

​API references

Before you start

1. Check the integration

2. Authorize provider access

User-delegated OAuth connections

Application client credentials and API keys

3. Verify the connection

Application access

1. Choose the access mode

2. Configure project variables

Microsoft

Confluence

ServiceNow

Box

Download response formats

Verify access before enabling writes

Provider references

API references