PermuteDocs
Go to Permute

Integration guide

Connect customer sources from your application

Create a temporary URL where customers authorize a source through Permute, then check completion from your server.

Your backend creates a connector session for a customer workspace. The customer opens its URL in a new tab or popup and enters credentials or signs in with the provider. Customers don't need Permute accounts. Google Drive requires the signed-in Permute application (hosted setup is not supported).

Ask someone else to connect from Permute

In Connectors, select Add Connector, choose a source, and select Share setup link. Create and copy the setup link, then send it to the person with access to that account. For an existing connector, select Ask someone else to connect in its details menu. The recipient does not need a Permute account.

Links expire after 15 minutes and use your existing connector permissions. New sources appear as Not connected until setup finishes. You can create a fresh link from that connector without creating another source. Removing your workspace access or required connector permissions prevents the link from being used. Refreshing the hosted page preserves the current setup session in the same browser tab (credential fields are not saved).

Configure your API key

Create an API key in organization settings with connector write permission in the customer workspace. Creating sources requires a connector creation grant; reconnecting an existing source requires write access to that source. Keep the key on your server.

Under Hosted connector return URLs, register each exact HTTPS URL customers may return to. This is optional: without a return URL, the page tells customers to close the window. Use a workspace per customer company and resolve that mapping on your backend before requesting a session.

Create and open a session

typescript
import { Providers } from '@permute/sdk';

// Run on your server after authenticating and authorizing the customer.
const client = orgClient.withWorkspace(customerWorkspaceId);
const session = await client.connectorSessions.create({
  provider: Providers.HUBSPOT,
  name: 'CRM',
  returnUrl: 'https://your-app.example/settings/connections',
});

// Persist this association on your server.
await saveConnectionSession(customerId, session.id, session.connectorId);
// Send only session.url to the authenticated customer's frontend.

Use Providers.HUBSPOT and the other Providers constants for supported provider IDs. String literals also have autocomplete and type checking (the type is exported as ConnectorProviderId). JavaScript requests are validated before they are sent. The list comes from Permute's connector registry; update the SDK to use newly added providers.

Open the returned URL as a normal link or in a popup launched by a user action. Preserve its fragment, which contains the launch token. The first screen shows the source, receiving organization, and sync scope without consuming the token. The page exchanges that token once for a browser session when the customer selects Continue. Both launch and browser access expire 15 minutes after issuance.

Keep URLs out of logs and analytics. Possession grants permission to configure that one source, so issue them only after checking the customer's access in your own application. The hosted page supports top-level browser windows; iframe embedding is blocked.

Check completion from your server

typescript
const session = await client.connectorSessions.get(savedSessionId);
if (session.status === 'completed') {
  const source = await client.sources.get(session.connectorId);
  // Use source availability to decide when to show data as ready.
}

Poll from your backend while the customer connects, for example every two seconds with backoff. Use the issuing API key and workspace. Check status again when the customer returns; a redirect or closed popup doesn't prove completion.

  • pending: the launch URL hasn't been redeemed.
  • in_progress: the customer is entering credentials or completing OAuth.
  • authorized: credentials are saved, but sync queueing still needs to finish.
  • completed: setup is complete and sync was queued. Manual credentials may still fail verification during sync.
  • expired: an unfinished session can no longer be used.

Completion is separate from data readiness. Inspect the resulting source before using its data. The browser session cannot query data, browse the workspace, or return saved credentials to your application.

Configuration and reconnecting

Your server can provide connector configuration in config. Hosted setup supports all or recommended table selection; configure manual table selection in Permute. Provider-specific credential setup, such as S3 role authorization, stays in the hosted flow. S3 table mappings supplied by your server are fixed; otherwise the customer supplies them.

typescript
const session = await client.connectorSessions.create({
  connectorId: savedConnectorId,
});

Reconnect sessions infer the provider and keep the connector's configuration. If you also supply a provider, it must match the existing connector. Pass the existing connector ID when replacing an expired link to avoid reserving another source. New-source sessions reserve an inactive connector at issuance; abandoned sessions leave that inactive source for your workspace administrators to remove or reuse.

Revoking the issuing key or removing its connector permissions disables unfinished sessions. Browser submissions and OAuth callbacks recheck those permissions. Repeated completion requests reuse the assigned connector.

See create session and session status for the generated REST schemas.