Create Connection

Connect an app that signs in with typed-in values, such as an API key or a username and password. Get the fields with GET /v2/connections/fields?app=…, send their values in credentials, and say whether the organization shares it (isCompany). MindCloud saves it as its connection form does, tests it when the app has a connection test, and answers the connection: status valid means the provider accepted it, invalid that it refused it (Test Connection says why). Secrets are never answered. OAuth apps need a person to sign in: use Create Connect Link.

POST

Headers

Optional headers

string

Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See Organizations.

Body

Arguments

stringrequired

An app id or slug, from List Universal Apps.

The app to connect, by its id or slug, from List Universal Apps.

string

The sign-in method's id, from GET /v2/connections/fields. Left out: the app's default.

The sign-in method to use, for an app with more than one, from GET /v2/connections/fields. Left out: the app's default.

string

A name for the connection. Left out: MindCloud names it after the account, as the app does. It can't contain a secret.

The connection's name, as the app lists it. It cannot contain a secret of the connection.

booleanrequired

Required. true: shared with the organization. false: the API key creator's own.

Required. true shares the connection with the organization; false makes it the API key creator's personal connection.

boolean

true makes it the organization's default connection for this app.

true makes it the organization's default connection for the app: a Universal run without connectionId and a new workflow step use it.

objectrequired

The field values by key, from GET /v2/connections/fields. Write-only.

Write-only. The values for the sign-in method's fields, by field key, from GET /v2/connections/fields: { "apiKey": "…" }. Never answered, logged or audited.

Response fields

idstring

Unique id of the connection.

namestring

The connection's name, as the app lists it. Null when it was never named.

nameSourcestring

How the name was set. Null for connections named before this was recorded.

generatedMindCloud named it when it was created, usually after the account it signed in as.
manualSomeone typed the name.

appIdstring

The app this connection signs into.

authTypestring

How it signs in to the app, as the app's sign-in method declares it: oAuth2, oAuth1, apiKey, basic, custom, ftp or none.

authenticationIdstring

The app's sign-in method it uses, for an app that offers more than one.

accountEmailstring

The email of the account it signed in as. Null when the app's sign-in does not report one (Slack's does not).

externalAccountIdstring

The signed-in account's id at the provider (a Slack workspace's team id), when the app reports one.

scopesarray of string

The permissions the provider granted at sign-in. Null for a connection that is not OAuth or last signed in before MindCloud recorded them; signing it in again records them.

environmentIdstring

The environment it is for, when a company keeps a connection per environment.

statusstring

The connection's status as of statusUpdatedOn: the result of its last sign-in, test or use.

statusUpdatedOndate

When the status last changed.

isDefaultboolean

True when it is the company's default connection for its app: a Universal API run that sends no connectionId uses it, and the editor picks it for a new step.

isCompanyboolean

True when the whole company shares this connection.

ownerstring

Whose connection it is. Filter with owner[in]=company,personal to leave out Embedded end users' and installations' connections.

companyShared with the company: usable by every member, or by who its share list names (Everyone, roles, teams).
personalOne person's: usable only by them (userId), or by who created it.
endUserAn Embedded end user's: used only on their behalf, never in a workflow step.
installationAn Embedded installation's: used only for that installation's runs.

usableByYouboolean

Whether this API key's creator may run Universal actions through it, and test or delete it: a shared connection with no share list, or whose share list gives them access (Everyone, their role or one of their teams; or they manage roles), or one of their own, the rule the Universal run applies. False for a shared connection whose share list gives them no access, and for Embedded end users' and installations' connections, which are used only on that end user's or installation's behalf. Another member's personal connection is not listed at all.

isGlobalboolean

True for a personal connection its owner can also use in every other company they belong to.

endUserIdstring

The embedded end user who owns it, if any.

installationIdstring

The embedded installation it belongs to, if any.

userIdstring

The user who owns it, if it is personal.

createdInstring

Where it was created: gravity (the MindCloud platform) or cirra. Null for connections created before this was recorded.

testedOndate

The last successful test.

expiresOndate

When the current sign-in expires (an OAuth access token's lifetime), if it does. MindCloud signs in again before the next use when the app allows it, so a past date on a valid connection usually means it has not been used since; status says whether that worked last time. Filter on this to catch sign-ins that cannot renew themselves.

authenticatedOndate

The last time someone authenticated it.

attemptedOndate

The last time someone started signing it in, whether or not they finished.

createdOndate

When the connection was created.

createdBystring

Who created it: a member's userId (List Members), or an embedded end user's id. With createdOn and authenticatedOn, this tells apart connections that share a name, such as several to the same Slack workspace.

updatedOndate

When it was last changed.

updatedBystring

Who last changed it.