Skip to main content

Documentation Index

Fetch the complete documentation index at: https://relevanceai-tsp-1169-docs-update.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

User Level Authentication is an Enterprise-only feature that is being rolled out. If you don’t have access yet, please reach out to your sales representative.
User Level Authentication enables agents to operate using each user’s individual authentication accounts for integrations, allowing multiple users to safely and privately use the same shared agent (especially in Chat) while only accessing their own data. Builders can configure this behavior per agent, and users only need to authenticate once per tool.

​
How User Level Authentication works

User Level Authentication changes how authentication works when multiple people use the same agent. Instead of everyone using a single shared account to access integrations (like Google Drive, Slack, or HubSpot), each user connects their own individual work accounts.

Builders configure

Choose which tool inputs require user level authentication using simple toggles

Users authenticate

Connect once per tool when first using the agent - credentials are saved for future use

Credentials persist

Authentication is automatically remembered and reused for all future agent runs

Defaults apply

Set preferred accounts for each integration that auto-populate in new agents
This means that when multiple team members use the same agent, each person only sees and accesses their own data within the connected integrations.

​
Why use User Level Authentication

Enhanced Security

Each user accesses integrations with their own credentials and permissions, reducing the security risks of shared accounts.

Privacy Protection

Users only see their own data. When an agent queries Google Drive or searches through emails, it only accesses the data that user has permission to see.

Access Control

Users can only access what they’re authorized to see in the external integration, based on their own account permissions rather than a shared account’s permissions.

Simplified Management

No need to manage shared credentials or worry about what happens when team members leave. Each user manages their own connections.

Audit Trail

Actions taken by agents are attributed to individual user accounts in external integrations, making it easier to track who did what.

​
Requirements for User Level Authentication

User Level Authentication works with tools that use OAuth authentication only. Supported:
  • Tool steps with OAuth account inputs (e.g., Google Sheets, Slack, HubSpot, Notion, Trello)
  • Any integration that uses OAuth to connect user accounts
Not supported:
  • Tools that use API key authentication
  • Python code steps (even when using OAuth via the Integration helper class)
  • Custom API calls with API key or bearer token authentication
If your tool uses API key authentication or Python steps, you’ll need to use a shared account instead of User Level Authentication.

​
Where User Level Authentication works

User Level Authentication is supported in the following contexts:

Chat

Users are prompted to connect their own account when an agent requests an authenticated action

Run tab

Same experience when running an agent directly in the agent builder

Workforces

When a workforce delegates to an agent with user level authentication configured, the user is prompted to authenticate

​
Limitations

Embedded chat is NOT currently supported. Users who embed agents on external sites via the embed widget cannot use user level authentication. For embedded agents, you’ll need to use a shared account for those integrations instead.

​
Setting up user level authentication

As a builder, you can configure User Level Authentication at the agent level.
To enable User Level Authentication:
  1. Head into your Agent and click Tools.
  2. Head to the Tool you want to set User Level Authentication on, and find the Input for the OAuth account. From here, click the agent input setting, which is currently set to ‘Set manually’.
  3. Then, set this to ‘Per-user authentication’.
When this is enabled, any agent using this tool will require each user to authenticate with their own account for this integration.
If you have asset-level authentication controls enabled through RBAC, users can also choose from project-level shared accounts instead of authorizing their individual accounts.
When dynamic authentication is enabled on a shared agent, all team members — not just admins — can add their own OAuth accounts. Members can only manage their own private accounts and cannot view or modify project-level shared accounts, which remain admin-managed.

​
User experience in Chat

When users interact with an agent in Chat that has User Level Authentication enabled, the authentication flow is seamless and intuitive.

​
First-time authentication

All team members — not just admins — will see the authentication prompt when using an agent with dynamic authentication enabled for the first time.
  1. When you run an agent that requires User Level Authentication for the first time, a pop-up appears with the guidance “Connect your account to use this tool.”
  2. Click the ‘Select connected account’ dropdown to choose an account. If your project has shared accounts available, they appear here alongside your personal options.
  3. To connect your own account, click ‘Add account’ to start the OAuth login flow for that integration.
  4. Follow the on-screen steps to log in. Your credentials are saved automatically for future runs.
Members can only add and manage their own private accounts. Project-level shared accounts are managed by project admins and cannot be modified by members.

​
Subsequent uses

After the first authentication:
  • The agent automatically uses the user’s saved credentials
  • No interruption to the agent’s execution
  • Users can change their default credentials in project settings if needed

​
Multiple tools

Authentication is required per tool, not per integration. If an agent uses two Google Drive tools, for example, you’ll be prompted to authenticate each tool separately on the first run. After initial setup, all credentials are remembered and reused automatically.

​
Managing default authentication

Users can manage their default authentication accounts for each integration at the project level, making it easy to control which accounts are used by agents.

​
Setting integration defaults

To set or change your default account for an integration:
  1. Click on ‘Integrations & API Keys’ in the sidebar
  2. Click on the integration you want to configure
Integration defaults pre-populate when you create new assets or use assets for the first time, saving you time and ensuring consistency across your agent interactions.

​
Privacy and account visibility

All team members — not just admins — can add their own OAuth accounts when dynamic authentication is enabled on an agent. Members can connect their own private credentials without needing admin intervention, and can only see and manage their own private accounts. They cannot view or modify project-level shared accounts. To protect privacy and security:
  • Private accounts are hidden - Your personal accounts won’t be visible to other users
  • Auths are private by default - When you connect a new account, it’s automatically set as private
  • Shared accounts - If your organization has shared project-level accounts, you’ll see those as options alongside your personal accounts

​
Frequently asked questions (FAQs)

If you need to change your authentication credentials, you can do so easily. During Chat, you’ll receive modal prompts that allow you to select existing credentials, add new ones, or mark a new credential as default. You can also manage your default credentials by going to Integrations & API Keys in the sidebar and selecting the integration you want to reconfigure.
Yes, if you have asset-level authentication controls enabled. When User Level Authentication is configured, you will see both your individual accounts and any shared project-level accounts available for selection. This gives you flexibility to choose the appropriate account based on the context.
User Level Authentication works with all integrations that support OAuth authentication in Relevance AI. This includes popular integrations like Google Drive, Gmail, Slack, HubSpot, Salesforce, and many others.
Yes, User Level Authentication is an Enterprise-only feature. If you would like access to this feature, please reach out to your sales representative.
User Level Authentication works in Chat, the Run tab (when running agents directly in the agent builder), and in Workforces (when a workforce delegates to an agent with user level authentication configured). However, it is NOT currently supported in embedded chat widgets on external websites.
User Level Authentication only works with OAuth-based integrations. If you don’t see the option to set ‘Per-user authentication’ on your agent input setting, it’s likely because:
  • Your tool uses API key authentication instead of OAuth
  • Your tool uses a Python code step
To use User Level Authentication, you need to use a tool that supports OAuth authentication (like Google Sheets, Slack, HubSpot, etc.). For tools that use API keys or Python steps, you’ll need to use a shared account instead.
No. User Level Authentication only supports OAuth-based integrations. If your integration uses API key authentication, Python code steps, or custom API calls with bearer tokens, you’ll need to use a shared account instead. Only integrations that use OAuth to connect user accounts (like Google Sheets, Slack, HubSpot, Notion, etc.) are compatible with User Level Authentication.
Yes. When dynamic authentication is enabled on a shared agent, all team members can add their own OAuth accounts — this is not limited to admins. Members see an “Add account” button with the guidance “Connect your account to use this tool.” Members can only manage their own private accounts; they cannot view or modify project-level shared accounts, which remain admin-managed.