Securing Your Tools

Introduction

Security is a critical aspect of working with tools on allmates.ai, particularly when integrating with external services that require authentication. This guide explores best practices for credential management, authentication methods, and strategies to maintain security while maximizing the functionality of your tools.

Credential Management Essentials

When working with tools that connect to external services, proper credential management is not just a good practice—it's essential for maintaining security and compliance. allmates.ai provides a robust system for handling sensitive information, but understanding how this system works will help you implement it effectively.

The Credentials JSON Object

At the heart of tool security is the "Credentials" JSON object—a structured way to store authentication information and sensitive parameters. This object is treated with special care within the allmates.ai platform:

• It's stored in an encrypted format in a dedicated secret manager system

• It's never exposed in plaintext after initial configuration

• It cannot be retrieved or viewed after being saved

• It must be completely replaced if changes are needed

This approach ensures that sensitive information remains secure throughout its lifecycle.

Credential Storage Security

The allmates.ai platform employs several layers of protection for your credentials:

• Encryption at Rest: All credentials are encrypted before being stored

• Access Controls: Strict permissions limit who can create or modify tool instances

• Audit Logging: Changes to tool configurations are logged for security monitoring

• Secure Transit: All communication is encrypted using TLS

• Isolation: Credentials for each tool instance are stored separately

These measures create a secure environment for your sensitive information, allowing you to confidently integrate with external services without compromising security.

Securing Different Types of Tools

Security configurations vary significantly between native tools and custom REST API tools.

Native Tools

For native tools, the credential configuration process is straightforward but requires precision:

• Follow the exact format: Each native tool has a specific JSON structure defined in its setup documentation

• No customization needed: Simply follow the template provided in the tool's documentation

• No Validation built-in: The system can not yet validate your credentials against the expected format. We are working on 😊

For example, if the Weather API Tool documentation specifies this credential structure:

{
  "customParameters": {
    "weatherApiKey": "YOUR_API_KEY"
  }
} 

You must use precisely this format, replacing only the YOUR_API_KEY placeholder with your actual API key.

The key point with native tools is simplicity—there's no need to design or customize the credential structure. Just follow the documentation exactly as provided for each specific tool.

REST API Tool

The REST API Tool is more flexible and offers several authentication options, but requires careful configuration:

Authentication Methods for REST APIs

Bearer Token Authentication:

Use this when the API requires a token in the Authorization header with the "Bearer" prefix.

{
  "bearerToken": "patgbfS8ChByP8dfezez8f72615ee51255e93f955bde50a918"
}

During execution, this will automatically add an Authorization: BearerpatgbfS8ChByP8dfezez8f72615ee51255e93f955bde50a918 header to all requests.

Custom Headers:

Use this for APIs that require specific headers for authentication or configuration.

{
  "headers": {
    "x-rapidapi-key": "f648d436eamshf19839832bafp1cb3b8jsn5e62e4fe1ecb",
    "x-rapidapi-host": "fresh-linkedin-profile-data.p.rapidapi.com"
  }
}

These headers will be included in every request made by the tool.

URL Parameters via Custom Parameters:

For APIs that require sensitive information in the URL path or query parameters:

{
  "customParameters": {
    "apiKey": "4e9ba705d6e34b1385563608250503"
  }
}

This must be used in conjunction with template variables in your OpenAPI schema (explained in the next section).

Combined Approach:

For APIs with complex authentication requirements, you can combine multiple methods:

{
  "bearerToken": "apiKeyToken",
  "headers": {
    "x-rapidapi-key": "f648d436eamshf1392f6eb212bafp1cb3b8jsn5e62e4fe1ecb",
    "x-rapidapi-host": "fresh-linkedin-profile-data.p.rapidapi.com"
  },
  "customParameters": {
    "clientId": "client_12345"
  }
}

Securing Parameters in the URL

A particularly challenging security scenario is when sensitive information needs to be passed directly in the URL. This is common with many public APIs that require API keys as query parameters.

Using Template Variables with the REST API Tool

When an API requires sensitive information in the URL:

1. Define the parameter in your OpenAPI schema using Jinja template syntax:

parameters:
  - name: apiKey
    in: query
    description: |
      Your API key. Required for all requests.
      
      ## For LLMs
      - You must use the exact value. This is a Jinja variable that will be replaced during tool execution.
      - Do not modify or generate a random API key.
    required: true
    schema:
      type: string
    enum: ['{{weatherApiKey}}']

2. Define the corresponding value in your Credentials JSON:

{
  "customParameters": {
    "weatherApiKey": "4e9ba705d6e34b1385563608250503"
  }
}

3. During execution, the platform will automatically replace {{weatherApiKey}} with the actual value from your credentials.

This approach ensures that sensitive parameters are:

• Never exposed in the OpenAPI schema

• Securely stored in the credential manager

• Automatically inserted at runtime

The variable names in the OpenAPI schema (inside the {{}} brackets) must exactly match the keys in your customParameters object.

Security Best Practices

Beyond the technical configurations, these best practices will help maintain the security of your tools:

Regular Credential Rotation

Periodically updating your credentials reduces the risk from potential exposures:

• Establish a regular schedule for credential updates

• Update immediately if you suspect any security issues

• Document the update process for continuity

• Verify functionality after each update

Remember that updating credentials on allmates.ai requires replacing the entire Credentials JSON object—you cannot edit or view existing credentials.

Principle of Least Privilege

Always provide the minimum access necessary:

• Use read-only access when possible

• Limit API key permissions to only required endpoints

• Create service accounts with restricted capabilities

• Regularly audit and remove unused permissions

Secure Development Practices for REST API Tool

When creating custom tools with the REST API Tool:

• Never hardcode credentials in your OpenAPI schemas

• Use template variables for all sensitive information

• Test with development credentials before using production keys

• Review schemas for security issues before deployment

Monitoring and Auditing

Stay vigilant about your tool usage:

• Monitor API usage for unusual patterns

• Review access logs regularly

• Set up alerts for potential security issues

• Conduct periodic security reviews of your tool configurations

Troubleshooting Credential Issues

Even with careful setup, you may encounter security-related issues:

Common Problems and Solutions

Authentication Failures:

• Verify that your credentials are current and correct

• Check for typos in your Credentials JSON

• Ensure the authentication method matches the API's requirements

• Confirm that your account has the necessary permissions

Template Variable Errors (REST API Tool):

• Ensure variable names match exactly between schema and credentials

• Check the syntax of your template variables (should be {{variableName}})

• Verify that all required variables are defined in the customParameters section

Credential Update Challenges:

• Remember that credentials cannot be viewed or edited—only replaced

• Keep a secure backup of your credentials during testing

• Document your credential configuration for future reference

When to Seek Help

Some situations warrant additional assistance:

• Persistent authentication failures despite correct credentials

• Unexpected security errors or warnings

• Complex multi-service authentication scenarios

• Integration with legacy systems that have unusual security requirements

Next Steps

Now that you understand how to secure your tools on allmates.ai:

1. Review your existing tool configurations for security best practices

2. Implement a credential rotation schedule for all your tools

3. Document your security approach for team continuity

4. Explore advanced security features of the allmates.ai platform

By following these guidelines, you'll create a secure foundation for your tool ecosystem while maintaining the flexibility and power that makes allmates.ai tools so valuable