Connections

Learn how to create and manage connections to external services in ThinkFleet using OAuth2, API keys, and other authentication methods.

5 min readBuilding Flows

Connections

Connections store the credentials ThinkFleet uses to authenticate with external services. They are created once and reused across any number of flows and agents.

Creating a Connection

There are two ways to create a connection:

From a Flow Step

When you add a piece action that requires authentication:

  1. Click on the Connection dropdown
  2. Select New Connection
  3. Follow the authentication flow (varies by piece)
  4. Name your connection (e.g., "Marketing Team Slack")

From the Connections Page

  1. Navigate to Connections in the sidebar
  2. Click New Connection
  3. Select the piece
  4. Complete the authentication
  5. Name and save

Authentication Types

OAuth2

OAuth2 is the most common authentication method for modern APIs. It uses a secure redirect-based flow where you authorize ThinkFleet in the service's own UI.

How it works:

  1. You click "Connect" in ThinkFleet
  2. A popup opens to the service's authorization page (e.g., Google, Slack)
  3. You log in and grant permissions
  4. The service redirects back to ThinkFleet with an authorization code
  5. ThinkFleet exchanges the code for access and refresh tokens
  6. Tokens are encrypted and stored

Token refresh: ThinkFleet automatically refreshes OAuth2 tokens before they expire. You never need to manually re-authenticate unless you revoke access from the service's side.

API Key

Some services use API keys — static secret strings that authenticate requests.

  1. Generate an API key in the external service's settings
  2. Paste it into the connection form in ThinkFleet
  3. The key is encrypted and stored
Service: OpenAI
API Key: sk-proj-abc123...

Basic Authentication

Username and password authentication, commonly used for SMTP, databases, and legacy APIs.

Username: admin@company.com
Password: ••••••••••

Custom Authentication

Some pieces define custom authentication schemas. These might include:

  • Connection strings (databases)
  • Multiple tokens (e.g., API key + secret)
  • Certificate-based auth
  • Custom header configurations

The piece defines what fields are needed, and the connection form adapts accordingly.

Managing Connections

Viewing Connections

The Connections page shows all connections in your project:

Column Description
Name The display name you assigned
App The piece/service this connection is for
Status Active, expired, or error
Created When the connection was created
Last Used When a flow last used this connection

Renaming Connections

Click on a connection name to rename it. Renaming is safe — flows reference connections by their internal ID, not by name.

Reconnecting

If a connection becomes invalid (e.g., you changed your password or revoked OAuth access):

  1. Click on the connection
  2. Click Reconnect
  3. Complete the authentication flow again
  4. All flows using this connection will automatically use the new credentials

Deleting Connections

Deleting a connection will cause any flows that use it to fail. ThinkFleet warns you and shows which flows are affected before you confirm deletion.

Connection References

When a flow step uses a connection, it creates a reference using the connection's external ID:

{{connections['my-slack-connection']}}

This reference is resolved at runtime to the actual credentials. You'll see this syntax in the flow configuration but you typically don't need to edit it manually.

Connection Security

Encryption

All connection credentials are encrypted at rest using AES-256 encryption. The encryption key is set via the AP_ENCRYPTION_KEY environment variable on your ThinkFleet instance.

Access Scope

Connections are scoped to a project. They cannot be accessed by flows in other projects. This ensures data isolation in multi-team environments.

Audit Trail

ThinkFleet logs connection events:

  • Connection created
  • Connection used (by which flow)
  • Connection reconnected
  • Connection deleted

Best Practices

  1. Use descriptive names — "Production Slack (Marketing)" is better than "Slack 1"
  2. Use least-privilege credentials — Only grant the permissions your flows actually need
  3. Rotate API keys regularly — Use the reconnect feature to update credentials
  4. Don't share connections across teams — Create separate connections per project
  5. Monitor connection status — Check the Connections page periodically for expired or errored connections

Troubleshooting

"Connection expired" Errors

OAuth2 tokens can expire if:

  • The refresh token was revoked by the service
  • The service has a hard token lifetime limit
  • You changed your password on the service

Fix: Click Reconnect on the affected connection.

"Invalid API key" Errors

  • Verify the key hasn't been rotated or deleted in the service's dashboard
  • Check that the key has the necessary permissions/scopes
  • Ensure there are no extra spaces or characters in the key

"Connection not found" Errors

This usually means:

  • The connection was deleted
  • You're referencing a connection from a different project
  • The connection ID was modified in the flow configuration

Fix: Edit the flow step and select a valid connection from the dropdown.

Next Steps