Mastering Tool Authorizations

Learn how to control who can configure, edit, and attach Tools to Mates. Understand the difference between tool management and usage to secure your integrations effectively.

Last updated About 1 month ago

Why use Tool Authorizations? 🛠️

In allmates.ai, Tools are the connectors that give superpowers to your Mates: database access, web search, image generation, or custom API connections.

Managing authorizations on Tools is distinct from managing Mates. It answers a specific governance question: "Who is allowed to manipulate this connector and use it to build Mates?"

This allows you to:

  1. Secure Credentials: Define who is authorized to update API keys or modify tool settings, preventing unauthorized changes to critical integrations.

  2. Control Distribution: Decide who can "plug" a specific tool into a new Mate.

  3. Prevent Deletion: Ensure critical tools used by many Mates are not accidentally deleted.

1. The Golden Rule: Management vs. Usage ⚠️

This is the most important concept to understand:

  • Tool Authorizations control MANAGEMENT: They define who can configure the tool, delete it, or attach it to a Mate.

  • Mate Authorizations control USAGE: If a user has access to a Mate, they can use the tools attached to that Mate, even if they have "No Access" to the tools directly.

Analogy: Think of a Tool as a "Key".

  • Tool Authorization: Defines who holds the key and who can put the key in a door (the Mate).

  • Mate Authorization: Defines who can walk through the door. Once the key is in the lock, anyone allowed through the door uses the key automatically.

2. Tool Authorization Matrix

This table summarizes what each role allows you to do with a Tool.

Role

Visibility (List)

Attach to a Mate

Configuration (Edit)

Manage Members

Delete Tool

Owner

✅

✅

✅

✅

✅

Admin

✅

✅

✅

✅

❌

User

✅

✅

❌

❌

❌

Viewer (List)

✅

❌

❌

❌

❌

No authorization

❌

❌

❌

❌

❌

  • Owner: The super-admin of the tool. The only one who can delete it.

  • Admin: Can configure the tool (change API keys, settings) and manage who can access it.

  • User: The "Builder". Can use this tool to create new Mates or enhance existing ones. Cannot see the internal credentials.

  • Viewer (List): Knows the tool exists in the library but cannot use it to build.

3. How to Manage Tool Permissions

Access management is handled from the "Toolbox" or the tool's detail page, under the "Authorizations" tab.

Default Behavior (Migration)

For existing tools, all organization members are set to Owner by default to ensure continuity. You should review this for sensitive tools.

Assigning Roles

  1. Go to Mates & Tools > Toolbox.

  2. Select a Tool and click Authorizations.

  3. For a specific member: Use "Add member" to assign a specific role (e.g., make your Lead Dev an Admin).

  4. For the organization: Adjust the "All organization members" row.

    • Recommendation: Set "All organization members" to List or No Access for sensitive tools (like a CRM connector). Set it to User for common tools (like Web Search).

4. Usage Scenarios

🔐 Scenario A: "The Corporate CRM Connector"

You have a tool connected to Salesforce with a master API Key. You want your Sales Ops team to build Mates with it, but you don't want them to see or change the API Key.

  • Setting:

    • You (IT): Owner.

    • Sales Ops Team: User.

    • All organization members: No Access.

  • Result: Sales Ops can attach the Salesforce tool to their agents. They cannot see the API key. The rest of the company doesn't know this tool exists.

🎨 Scenario B: "The Image Generator"

You have an Image Generation tool that you want everyone to be able to use in their own custom Mates.

  • Setting:

    • All organization members: User.

  • Result: Anyone in the company can create a new Mate and attach the Image Generator to it.

🕵️ Scenario C: "The Sensitive HR Database"

A tool connects to a SQL database with salaries. Only you should manage it. However, you have created an "HR Assistant Mate" for the HR Director.

  • Setting:

    • Tool Authorization: You are Owner. HR Director has "No Access".

    • Mate Authorization (on the HR Assistant): HR Director is User.

  • Result: The HR Director CAN chat with the Mate and get salary info (because they have rights on the Mate). They CANNOT take the database tool and attach it to another public Mate (because they have no rights on the Tool).

5. Frequently Asked Questions (FAQ)

Q: I have "No Access" to a tool, but I can use it when chatting with a Mate. Is this a bug? A: No, this is by design. Access to the functionality is inherited from the Mate. Access to the tool object (for building/editing) is what Tool Authorizations control.

Q: I am a "User" on a Tool. Can I see the API Key or configuration? A: No. The User role on a tool allows you to attach it to a Mate, but it treats the configuration as a "black box" to protect credentials. You need to be Admin or Owner to see settings.

Q: Can I delete a tool if I am an Admin? A: No. Only the Owner can delete a tool. This prevents accidental deletion of tools that might be used by critical Mates in production.

Q: What happens if I remove a user's right to a Tool, but they are still Owner of a Mate using it? A: They can still use their Mate (and thus the tool) for chatting. However, if they try to edit their Mate's configuration, they will see the tool but won't be able to re-attach it if they detach it.