Delegation setup

Open Hosted Connect, then store execution scope.

Hosted Connect gives the customer a Vela-owned setup flow while your app keeps the resulting customerTenantId and delegationId as its source of truth.

Hosted Connect

The developer app opens Hosted Connect so the customer can authenticate, choose or create an LLM provider connection, and grant a delegation.

Create a connect session

import { createVelaClientFromEnvironment } from "@vela/sdk";

const client = createVelaClientFromEnvironment({ env: process.env });

export async function GET() {
  const session = await client.createConnectSession({
    customerTenantId: "tenant_acme",
    returnUrl: "https://your-app.example.com/settings/ai",
  });

  return Response.redirect(session.connectUrl);
}

App ID is optional in calls

When the client was created with VELA_APP_ID, SDK client methods fill appId automatically.

Customer can be deferred

If the app cannot choose a customer tenant yet, omit customerTenantId and bind it after Hosted Connect login.

Reconnect can reuse delegation

Pass an existing delegationId when the customer should update the same delegation instead of creating a new one.

Execution scope

Vela authorizes one customer delegation at a time. Your app chooses where that scope comes from: env for local demos, database or session for production, or Hosted Connect return URL for browser redirect flows.

Return URL scope

browser or route callback

import { resolveVelaExecutionScopeFromUrl } from "@vela/sdk";

const scope = resolveVelaExecutionScopeFromUrl(window.location.href);

if (scope) {
  localStorage.setItem("vela-scope", JSON.stringify(scope));
}

Saved object scope

session or database payload

import { resolveVelaExecutionScope } from "@vela/sdk";

const scope = resolveVelaExecutionScope(savedVelaSettings);

if (!scope) {
  throw new Error("Vela delegation is not configured.");
}

Hosted Connect appends velaCustomerTenantId and velaDelegationId to the return URL. If your app uses different query names, pass queryParameterNames to resolveVelaExecutionScopeFromUrl().