ToolYour REST API Authentication Guide

Welcome, developers! This guide provides a step-by-step walkthrough to successfully authenticate your first REST API request with ToolYour. Correct ToolYour API authentication is fundamental for accessing our robust suite of tools, whether you're integrating our REST API directly into your applications or leveraging our Model Context Protocol (MCP) server for your AI agents.

By following this guide, you will learn how to create and manage your API keys, understand the required header format for REST calls, make a successful authenticated request, and troubleshoot common authentication issues. We'll ensure your API key is handled securely and that you understand the shared quota system that powers both our REST API and MCP.

Prerequisites

Before you send your first authenticated request, ensure you have:

1. A ToolYour Account: If you don't have one, sign up at https://www.toolyour.com/signup.

2. An API Key: You'll generate this from your ToolYour dashboard, as detailed in the next section.

3. Basic understanding of REST APIs: Familiarity with HTTP methods (GET, POST), headers, and JSON request/response bodies will be helpful.

4. A tool for making HTTP requests: curl is used in our examples, but any HTTP client or programming language can be used.

Create an API key

Your API key is a unique identifier that authenticates your requests to the ToolYour platform. Think of it as your digital passport for our APIs.

To generate your API key:

1. Log in to your ToolYour account at https://www.toolyour.com.

2. Navigate to the API Keys section in your dashboard. You can directly access it here: https://www.toolyour.com/dashboard/api-keys.

3. Click the "Create New API Key" button.

4. Give your key a descriptive name (e.g., MyDevEnvironmentKey, ProductionAppKey) to help you identify its purpose later.

5. Your new API key will be displayed. It will start with the prefix ty_. Copy this key immediately and store it securely. For security reasons, it will only be shown once. If you lose it, you'll need to generate a new one.

Secure Key Storage

Treat your API key like a password. Never hardcode it directly into your application's source code, commit it to version control (like Git), or expose it in client-side code. Instead, use secure methods for storage and retrieval:

• Environment Variables: Load the API key from an environment variable (TOOLYOUR_API_KEY) when your application starts.
• Secrets Management Services: For production environments, consider using dedicated secret management services (e.g., AWS Secrets Manager, HashiCorp Vault).
• Configuration Files: If using configuration files, ensure they are external to your codebase and properly secured (e.g., .env files for local development, excluded from version control).

Important: All API keys created under your account share the same monthly credit quota. For a comprehensive overview of your account and API keys, including credit usage and limits, refer to our Account and Keys documentation.

X-Api-Key header format

All authenticated requests to the ToolYour REST API require your API key to be sent in a specific HTTP header. This header is named X-Api-Key.

The format is straightforward:

X-Api-Key: YOUR_API_KEY_HERE

Replace YOUR_API_KEY_HERE with the actual API key you generated from your dashboard (e.g., ty_abcdef1234567890abcdef1234567890). This header must be included in every API request you make that requires authentication. Without it, or with an invalid key, your request will be rejected.

Here's an example of how this header would look in a typical HTTP request using curl:

curl -X POST \
  https://api.toolyour.com/api/v1/documents/docx-to-pdf \
  -H "X-Api-Key: ty_YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary "@./input.docx" \
  --output "output.pdf"

In this example, -H "X-Api-Key: ty_YOUR_SECRET_API_KEY" correctly sends your API key.

First authenticated request pattern

Let's make a real, authenticated call to the ToolYour REST API. We'll use the docx-to-pdf converter tool as an example. This tool converts a Microsoft Word document (DOCX) into a PDF.

Prerequisites for the example:

• Your ToolYour API Key: Make sure you have it copied.
• A sample DOCX file: Create a simple Word document (e.g., sample.docx) for conversion.
• curl installed on your system.

Step-by-step example using curl

1. Prepare your input file: Create a sample.docx file.

2. Execute the curl command: Replace ty_YOUR_SECRET_API_KEY with your actual API key.

   curl -X POST \
     https://api.toolyour.com/api/v1/documents/docx-to-pdf \
     -H "X-Api-Key: ty_YOUR_SECRET_API_KEY" \
     -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
     --data-binary "@./sample.docx" \
     --output "output.pdf"
   

   Explanation of the command:

   • -X POST: Specifies the HTTP method as POST.
   • https://api.toolyour.com/api/v1/documents/docx-to-pdf: This is the target endpoint for the DOCX to PDF conversion tool. You can find other tool endpoints and their schemas in our Developer Documentation.
   • -H "X-Api-Key: ty_YOUR_SECRET_API_KEY": This is your authentication header, including your API key.
   • -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document": Specifies the MIME type of the input file.
   • --data-binary "@./sample.docx": Sends the content of your sample.docx file as the request body. The @ symbol tells curl to read the content from the specified file.
   • --output "output.pdf": Saves the response body (the converted PDF) to a file named output.pdf.

Interpreting the response

• Success (HTTP 200 OK): If your request is successful, you will receive an HTTP 200 OK status. The converted PDF file will be saved as output.pdf in your current directory. A successful tool call, like this conversion, consumes credits from your account. Tools typically cost between 1 and 10 credits per successful call.
• Free Tier Usage: The free plan offers 500 credits per month. It also includes a throughput limit of 30 successful tool runs per rolling 60-second window. Invalid requests generally do not consume credits.

Congratulations! You've just made your first authenticated request to the ToolYour REST API. You can explore more endpoints and their specific requirements in our Calling Tools documentation.

Common auth errors

Encountering an error is a normal part of development. Here are some common authentication-related errors you might see when using the ToolYour API and how to troubleshoot them:

• HTTP 401 Unauthorized:

  • Meaning: This error indicates that the API key provided is missing or invalid.
  • Troubleshooting:
    • Check X-Api-Key header: Ensure the X-Api-Key header is present in your request.
    • Verify API Key: Double-check that your API key is correct and hasn't been mistyped or truncated. Remember, API keys start with ty_. You can verify your active keys on your dashboard.
    • Key Expiration/Revocation: Confirm your API key has not been revoked or expired (though ToolYour keys generally don't expire unless explicitly revoked by you).

• HTTP 403 Forbidden:

  • Meaning: This error often means your authentication is valid, but you lack the necessary permissions to access the requested resource, or you've exceeded your account's quota limits.
  • Troubleshooting:
    • Quota Limits: If you are on the free plan (500 credits/month) or a paid plan and have exhausted your credits, further requests will be blocked. Check your usage on the dashboard. Your credit quota resets on the 1st of each calendar month. If you hit your limit, you can upgrade your plan at https://www.toolyour.com/pricing to resume access or wait for the next month's reset.
    • Throughput Limits: Exceeding 30 successful tool runs within a rolling 60-second window on the free plan will also result in a 403 error. Pace your requests to stay within this limit.
    • Invalid Tool/Endpoint: Ensure the tool or endpoint you are trying to access exists and your account has access to it.

For a more comprehensive list of potential errors and their explanations, consult our Errors documentation.

MCP uses the same key

ToolYour provides a remote Model Context Protocol (MCP) server that enables AI agents to plan, execute, and verify complex jobs like ship-gate analysis, SEO audits, and security checks. Critically, the same API key you use for the REST API also authenticates your requests to the ToolYour MCP server.

This means your monthly credit quota is shared across both REST API calls and MCP tool executions. Whether your AI agent triggers a solve_task via MCP or you make a direct POST request to a REST endpoint, both activities draw from the same credit pool.

For example, when an AI agent sends a solve_task request to the ToolYour MCP server, it uses your API key for authentication:

{
  "goal": "Analyze the SEO health of the homepage and suggest improvements.",
  "input": {
    "url": "`https://yoursite.com/homepage`"
  }
}

In an MCP workflow, your AI agent typically follows a plan_task (which is free) to outline steps, then solve_task or run_playbook to execute tools. After execution, the host applies any suggested loop.nextActions (patchType, acceptance, roleHint), and finally, verify_task is used to check progress until loop.gate is pass or loop.stop. Browsing the catalog and plan_task requests do not consume credits, but running a tool through solve_task or run_playbook does consume weighted credits, similar to REST calls.

To get started with connecting your AI agent to ToolYour's MCP server, including client setup instructions, visit our ToolYour MCP documentation.

FAQ

Q: How do I create a ToolYour API key? A: You can create API keys by logging into your ToolYour dashboard and navigating to https://www.toolyour.com/dashboard/api-keys.

Q: Can I have multiple API keys for my account? A: Yes, you can create multiple API keys. Each key will be associated with your account.

Q: Do all my API keys share the same credit quota? A: Yes, all API keys under a single ToolYour account share the same monthly credit quota.

Q: What is the free tier credit limit and throughput? A: The free plan includes 500 credits per month. Tools cost 1–10 credits per successful call. There's also a limit of 30 successful tool runs per rolling 60-second window.

Q: Do invalid or failed API requests consume credits? A: Generally, invalid requests or calls that result in errors (e.g., due to malformed input, not authentication issues) do not consume credits. Credits are typically charged only for successful tool executions.

Q: When does my monthly credit quota reset? A: Your credit quota resets on the 1st of each calendar month.

Q: Can I use the same API key for both REST API calls and MCP requests? A: Yes, the same API key authenticates both your direct REST API requests and calls made to the ToolYour MCP server from your AI agents.

Q: Where can I find detailed documentation for ToolYour's API endpoints? A: All our API endpoints and their schemas are documented on our main Developer Documentation page.

Conclusion

Mastering ToolYour API authentication is your gateway to leveraging our powerful tools for your development needs and AI agent workflows. By correctly setting up your API key, understanding the X-Api-Key header, and implementing secure storage practices, you ensure reliable access to the ToolYour platform.

We encourage you to explore the full capabilities of the ToolYour API and MCP. From automating file conversions to running comprehensive SEO or security audits with AI agents, ToolYour provides the robust backend you need.

For further exploration:

• Developer Documentation: https://www.toolyour.com/developers/docs
• Account and Key Management: https://www.toolyour.com/developers/docs/account-and-keys
• ToolYour MCP Overview: https://www.toolyour.com/developers/mcp