Authenticate your end users

Toolhouse provides tools to authenticate your end users to commonly used services like Gmail, Slack, and others. As a tool-agnostic platform, you can use a selection of tools based on the service you want to make available to your AI models (and to your end users).

At present, Toolhouse supports Pipedream and Composio.

Managed authentication

Pipedream is enabled by default and it gives your AI models the ability to securely access user accounts via third party APIs. This allows your users to send Slack messages, read and manipulate a Gmail inbox, and other actions. Toolhouse regularly publishes more actions, which will be available to your app and AI models out-of-the-box.

Similarly to Pipedream, Composio allows access to common actions via third-party API. Accessing Composio requires that you provide a Composio API key.

Toolhouse does not handle credentials

Credentials, including access tokens, are handled directly by the authentication provider. This means Toolhouse will never store your user's credentials.

First-party authentication

Toolhouse can handle authentication for you. If you have a valid OAuth Client ID, you can configure your OAuth client to authenticate your users. This allows full flexibility and it won't require you to use any third-party authentication providers.

First-party authentication is available to Toolhouse Pro users. Contact the Toolhouse team to enable this authentication method.

How authentication works in Toolhouse

The authentication flow is handled by Toolhouse and the authentication provider. We'll cover a scenario where your end users requests the AI agent to check for unread messages in their Gmail inbox.

1. First, give each of your end users an ID using user metadata: th.set_metadata("id", <user id>). This will enable Toolhouse and the authentication provider to determine the right permissions and services for each one of your users.

   1. Note: User IDs are automatically hashed by Toolhouse. Neither Toolhouse nor the authentication provider will be able to see your User IDs in cleartext.

2. Your user requests to check for unread messages in their inbox through your app.

3. In the completion request (or framework request) your app sends a request to Toolhouse to retrieve the necessary tools via th.get_tools().

4. Toolhouse provides the Gmail tools to the AI agent.

5. The agent calls the Gmail inbox tools.

6. Toolhouse understands the request and checks with the authentication provider to see if the user is authenticated.

If the user is authenticated, Toolhouse executes the request as received from the agent, and returns the result.

If the user is not authenticated, Toolhouse will trigger the authentication flow on behalf of your app:

1. Toolhouse will ask the authentication provider to generate an authentication link. Once received, it will return it to the agent.

2. The agent responds with the authentication link. Your app can then present the link to the user in the most suitable way for your user experience.

3. The user completes the authentication flow with the authentication provider.

4. The authentication provider marks the user as authenticated and notifies Toolhouse.

5. Toolhouse executes the inbox tool request using the LLM and returns the result.