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

Connect the account

Create the connection with a label:

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:

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.

Check it

getstream agents connections list --connector github

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

Name it in the agent

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.

Test it

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

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.

See whose account it uses

getstream agents tools support
CONNECTOR  NAME    ACCOUNT                 GRANT      REQUIRED  SANDBOX
github     github  App connection company  All tools  no        no

In the Dashboard

Open the connector

In the Stream Dashboard, go to Agents > Library > Connectors, open GitHub and click Create connection.

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.

Use it

Name it in agent.yaml and test it as in the CLI steps.

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:

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:

agents/support/agent.yaml
name: support
mode: text
llm: llm-fast
connectors:
  - name: shopify
    connection: shop
getstream agents test support --sync

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

Delete it

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: an HS256 JWT of {"server": true} signed with your API secret.

Create the connection

Create it with "auth_scheme": "bearer":

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:

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:

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:

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

Let each user connect their own account, from the dashboard or your own app.

Tools

See a connection's tools and offer only the ones the agent needs.

Custom MCP servers

Any MCP server: a public one, or one behind a key.

Connectors

What a connector is, a quickstart, and whose account it uses.

Troubleshooting

Errors you may see, why, and what to do.