Create a hosted connector session – POST /v1/connector-sessions

POST/v1/connector-sessions

betaapiKeyworkspace

When to use

Let a customer authorize one source through a Permute-hosted page.

For agents

Call from your server after authenticating the customer. Save the session-to-customer mapping. Return URLs must be registered on the API key. Treat the launch URL as a secret.

Example

typescript

import { PermuteClient, Providers } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.connectorSessions.create({
  provider: Providers.HUBSPOT,
  name: 'CRM',
  returnUrl: 'https://your-app.example/settings/connections',
});

Request body

json

{
  "provider": "hubspot",
  "name": "CRM",
  "returnUrl": "https://your-app.example/settings/connections"
}

Response

json

{
  "data": {
    "id": "cses_aaaaaaaaaaaaaaaaaaaaaaaa",
    "connectorId": "conn_aaaaaaaaaaaaaaaaaaaaaaaa",
    "provider": "hubspot",
    "status": "pending",
    "connectorStatus": "inactive",
    "expiresAt": "2026-09-21T12:15:00.000Z",
    "url": "https://app.permute.ai/connect/cses_aaaaaaaaaaaaaaaaaaaaaaaa#token=EXAMPLE_LAUNCH_TOKEN"
  }
}