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 short-lived handoff with POST /oauth/connect/session. This example connects GitHub for the current user within support-assistant:
create-oauth-session.sh
Open the returned connect_url in a browser before expires_at, then complete provider consent. The example returns to Veryfront afterward. Custom return URLs must be allowed by the deployment. Creating a handoff does not complete authorization. Use scope: "project" only when you intend a shared project connection and have the required project permission.

​
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 connected accounts with GET /connections:
list-connections.sh
Confirm the intended provider account is connected. Then call a read-only tool from that provider’s reference, using arguments for resources the account can access. Enable the required project tools separately. Successful authorization does not automatically select every tool for an agent or grant write access. If a call fails, check the selected connection, project tool policy, and provider permissions. For credential-based integrations, also check the variable names and runtime environment.

​
API references