---
title: 'How Connections Work'
description: 'What a connection is, personal and shared connections, the default for each app, and how the Universal API runs an app action through one.'
---

A **connection** is a signed-in account in another app: a Slack workspace, a HubSpot portal, a NetSuite account. Workflows, Cirra and the Universal API all reach an app through a connection. MindCloud stores the secrets and never answers them: no endpoint returns a password, token or key.

## Personal and shared

- A **shared** connection (`isCompany: true`) belongs to the organization. Anyone whose role allows it can use it.
- A **personal** connection belongs to one member. Only that member, and the API keys they created, can use it. Some personal connections are **global** (`isGlobal: true`): their owner can use them in every organization they belong to.
- Each app can have one **default** connection (`isDefault: true`). A step or a Universal run that names no connection uses it.
- **Embedded** end users have connections of their own, which their end user owns: [Connect end-user apps](/docs/api/rest/introduction/embedded-api).

[List Connections](/docs/api/rest/actions/list-connections) lists the connections your key's creator can use, each app's default first, with `usableByYou` telling you whether this key may use each one. Filter with `app=slack` to see one app's.

## Status

A connection's `status` is the result of its last sign-in, test or use, and `valid` says whether it works; filter on either to find connections that need attention. [Test Connection](/docs/api/rest/actions/test-connection) checks it against the app now, and says why when it fails. Test one that has not been used lately before you rely on it. [Delete Connection](/docs/api/rest/actions/delete-connection) removes one, and refuses while an active workflow still uses it, naming those workflows.

## Who may use a shared connection in Cirra

A shared connection's share list decides who may use it in Cirra, and how far: Everyone, roles and teams, each with an access level (read, read and write, full, or a custom table per record type). [Get Connection Shares](/docs/api/rest/actions/get-connection-shares) reads the list and [Update Connection Shares](/docs/api/rest/actions/update-connection-shares) replaces it. A shared connection with no list is open to every member.

## The Universal API

The Universal API runs any published app action through a connection, with the same arguments and answers for every app:

1. [List Universal Apps](/docs/api/rest/actions/list-universal-apps) finds the app, and [List Universal Actions](/docs/api/rest/actions/list-universal-actions) its actions.
2. [Get Universal Action](/docs/api/rest/actions/get-universal-action) lists an action's arguments; [Resolve Universal Lookup](/docs/api/rest/actions/resolve-universal-lookup) finds the ids an argument takes, such as a Slack channel by name.
3. [Run Universal Action](/docs/api/rest/actions/run-universal-action) runs it. Name the account with `connectionId`; without one, the app's default connection is used, or its only valid one.

Each app's actions are documented in the [Universal API](/docs/universal) section.