# App connection

Generally your agent should use the company's own accounts. For instance, your support agent can check your GitHub issues to tell a customer whether their bug is fixed. Connect the company's account once as an app connection, and every conversation uses it.

## With the CLI

1. **Connect the account**

   Create the connection with a label:

   ```sh
   curl -fsSL https://getstream.io/cli/beta/install.sh | bash # the agents commands are in the beta CLI
   getstream agents connections create github --label company
   ```

   GitHub's consent opens in your browser. Sign in as the company's GitHub account and click **Authorize**. The CLI prints `Connected: github / company`.

   To use a GitHub personal access token instead, pass it on stdin:

   ```sh
   echo "$GITHUB_TOKEN" | getstream agents connections create github --label company --token -
   ```

   The CLI checks the token with GitHub. If GitHub refuses it, the CLI saves nothing and tells you so.

2. **Check it**

   ```sh
   getstream agents connections list --connector github
   ```

   The new row shows LABEL `company`, OWNER `App` and STATUS `Connected`.

3. **Name it in the agent**

   ```yaml title="agents/support/agent.yaml"
   name: support
   mode: text
   llm: llm-fast
   connectors:
     - name: github
       connection: company # the label of a connection the app owns
   ```

   `connection` takes the connection's label or its id.

4. **Test it**

   Nobody is asked to sign in, so a test in the terminal uses it too:

   ```sh
   getstream agents test support --sync
   ```

   Ask: "What are the open issues in GetStream/awesome-ai-news?" to see the agent read GitHub as the company.

5. **See whose account it uses**

   ```sh
   getstream agents tools support
   ```

   ```text
   CONNECTOR  NAME    ACCOUNT                 GRANT      REQUIRED  SANDBOX
   github     github  App connection company  All tools  no        no
   ```

## In the Dashboard

1. **Open the connector**

   In the [Stream Dashboard](https://getstream.io/signin/), go to **Agents > Library > Connectors**, open **GitHub** and click **Create connection**.

2. **Fill in the connection**

   **Authentication** starts on **OAuth** and **Owner** on **Signed-in user**. Pick **Bearer token** and **App** instead. Type `company` in **Label**, paste the token in **Token**, then click **Create connection**.

   The Dashboard checks the token with GitHub. If GitHub refuses it, the dialog stays open and says `The token did not work with the provider: The provider rejected the stored token or key; replace it with PUT /v1/agents/connections/{id}/credentials. Enter another one, or cancel to delete the connection.` Paste another token, or click **Cancel** to delete the connection.

3. **Use it**

   Name it in `agent.yaml` and test it as in [the CLI steps](#with-the-cli).

## A shop with no sign-in

Shopify needs the shop's `myshopify.com` address and no sign-in, so the connection is connected as soon as you create it:

```sh
getstream agents connections create shopify --label shop --input shop=mystore.myshopify.com
```

In the Dashboard, open **Shopify** under **Agents > Library > Connectors** and click **Create connection**. **Owner** starts on **Signed-in user**: pick **App**. Type `shop` in **Label** and the address in **shop**, then click **Create connection**. The connection's page opens, and the connection is already connected.

Then use it with `connection: shop`:

```yaml title="agents/support/agent.yaml"
name: support
mode: text
llm: llm-fast
connectors:
  - name: shopify
    connection: shop
```

```sh
getstream agents test support --sync
```

Ask: "Do you ship to Canada?" to see the agent search the shop's policies.

## Delete it

```sh
getstream agents connections delete company
```

The CLI refuses while an agent names the connection under `connection`. Remove the entry from the agent's `connectors` and sync it first.

>
> **Warning:** If it was the only entry, keep `connectors: []`: a sync without the key leaves the agent's connectors as they were.
>
> `--force` deletes the connection anyway, and leaves the agent naming a connection that no longer exists.
>

## With the API

Your server can create the same connection. `$STREAM_ACCELERATION_URL` is your router's URL, and `$SERVER_TOKEN` is a [server token](https://getstream.io/agents/docs/auth/): an HS256 JWT of `{"server": true}` signed with your API secret.

### Create the connection

Create it with `"auth_scheme": "bearer"`:

```bash
curl -X POST "$STREAM_ACCELERATION_URL/v1/agents/connections" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connector_id": "github", "owner": {"type": "app"}, "label": "company", "auth_scheme": "bearer"}'
```

It returns the connection, `pending`, with its `id` and `"revision": 1`.

### Save the token

Use that `id` as `$CONNECTION_ID`:

```bash
curl -X PUT "$STREAM_ACCELERATION_URL/v1/agents/connections/$CONNECTION_ID/credentials" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected_revision": 1, "values": {"token": "github_pat_..."}}'
```

`expected_revision` is the connection's `revision` as you last read it. The connection is now `connected`, and the token is never shown again.

### Check it

>
> **Warning:** Unlike the CLI and the Dashboard, the API doesn't check the token when you save it, so a made-up one shows `connected` too.
>

Ask GitHub once after saving:

```bash
curl -X POST "$STREAM_ACCELERATION_URL/v1/agents/connections/$CONNECTION_ID/validate" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN"
```

The `status` stays `connected` when GitHub takes the token, and turns to `needs_reauthorization` when it refuses it.

### Connect a shop

Create the Shopify connection with the shop's address, then save empty credentials to connect it. Use the `id` the first call returns as `$CONNECTION_ID`:

```bash
curl -X POST "$STREAM_ACCELERATION_URL/v1/agents/connections" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connector_id": "shopify", "owner": {"type": "app"}, "label": "shop", "inputs": {"shop": "mystore.myshopify.com"}}'

curl -X PUT "$STREAM_ACCELERATION_URL/v1/agents/connections/$CONNECTION_ID/credentials" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected_revision": 1, "values": {}}'
```

## Going further

- [User connection](https://getstream.io/agents/docs/connectors/each-user-account/): Let each user connect their own account, from the dashboard or your own app.
- [Tools](https://getstream.io/agents/docs/connectors/choosing-tools/): See a connection's tools and offer only the ones the agent needs.
- [Custom MCP servers](https://getstream.io/agents/docs/connectors/mcp/): Any MCP server: a public one, or one behind a key.
- [Connectors](https://getstream.io/agents/docs/connectors/): What a connector is, a quickstart, and whose account it uses.
- [Troubleshooting](https://getstream.io/agents/docs/connectors/troubleshooting/): Errors you may see, why, and what to do.

---

For the most recent version of this documentation, visit [https://getstream.io/agents/docs/connectors/shared-account/](https://getstream.io/agents/docs/connectors/shared-account/).