Skip to navigation
API ReferenceConnections

Connect

Creates a Polytomic Connect session and returns a URL for creating or reconnecting a Connection.

Open the returned URL, or send it to the person who will set up the Connection. Polytomic Connect guides them through authentication and configuration, then redirects them to redirect_url.

Each session can create or reconnect one Connection.

See also:

Authentication

AuthorizationBasic

This is the Polytomic deployment key (on-premises only)

OR
AuthorizationBearer
This is the Polytomic API key

Headers

X-Polytomic-VersionstringRequired

Request

This endpoint expects an object.
namestringRequired
Name of the new connection. Must be unique per organization.
accesslist of enumsOptional

Access levels the new connection requests: [“read”] for read-only access, or [“read”, “write”] for full access, the default. Only some connection types support read-only access.

Allowed values:
connectionstringOptionalformat: "uuid"
The id of an existing connection to update
darkbooleanOptional
Whether to use the dark theme for the Connect modal
organization_idstring or nullOptionalformat: "uuid"

Ignored for user and organization-scoped API keys, which always act in their own organization

redirect_urlstringOptional

URL to redirect to after the hosted Connect flow finishes. Required for hosted Connect; omit it to mint a session for the embedded form (@polytomic/connect-react).

ttlinteger or nullOptional
Connect session lifetime in seconds. Defaults to 300 and cannot exceed 604800.
use_organization_namebooleanOptional

Whether to display the target organization name instead of the partner name in the Connect modal. Defaults to false; organizations without a partner always display their organization name.

whitelistlist of strings or nullOptional
List of connection types which are allowed to be created. Ignored if type is set. The embedded form shows one connection type, so send exactly one entry.
typestringOptionalDeprecated
Connection type to create

Response

OK
dataobjectOptional
The Connect session

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error