Skip to main content
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. Use the provider’s documented authentication model. OAuth needs a consent flow, while API-key and client-credentials integrations need the listed environment variables.

​
1. Check the integration

Call GET /integrations to inspect the catalog available to your credential:
list-integrations.sh
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.

​
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
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.

​
API keys and client credentials

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}/environment-variables:
set-provider-credential.sh
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
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.

​
API references