Connect Unkey to AI Agents: Analyze Traffic and Manage Auth Flow

You want to connect Unkey to an AI agent so your internal systems can independently provision API keys, analyze traffic anomalies, dynamically adjust rate limits, and manage complex Role-Based Access Control (RBAC) structures based on user behavior. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code and maintain complex API wrappers for authentication management.

Giving a Large Language Model (LLM) read and write access to your API management infrastructure is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the nuances of global edge propagation, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Unkey to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Unkey to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Unkey, bind them natively to an LLM using your preferred framework (LangChain, LangGraph, CrewAI, or Vercel AI SDK), and execute complex infrastructure operations. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Unkey Connectors

Building AI agents is easy. Connecting them to highly distributed, edge-first infrastructure APIs is hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely, especially with a platform optimized for sub-millisecond edge latency like Unkey.

If you decide to build a custom integration for Unkey, you own the entire API lifecycle. Unkey introduces several highly specific infrastructure challenges that break standard LLM assumptions.

The Edge Propagation Delay

Unkey operates on a globally distributed edge architecture. When you update a key's permissions or roles, those changes are immediately acknowledged by the control plane but take time to propagate to the edge. The Unkey API explicitly notes that changes via endpoints like unkey_keys_set_permissions can take up to 30 seconds to propagate across all edge regions.

LLMs are inherently impatient and linear. If an agent adds a role to a key and immediately tries to verify that key's permissions in the next step, the verification will likely return the old state. Hand-coding this requires injecting complex retry logic or hard-coded wait states into the LLM's system prompt so it understands the concept of eventual consistency.

SQL-Based Analytics Interrogation

Standard REST APIs use query parameters for filtering (?start_date=x&status=y). Unkey's analytics engine allows you to query key verifications using actual SQL SELECT statements via their unkey_analytics_get_verifications endpoint.

While LLMs are generally good at SQL, giving them a raw endpoint without strict guardrails is dangerous. The agent must understand the exact table schema Unkey expects, and it must be restricted strictly to SELECT operations. Without a structured tool definition and schema validation layer, an agent might hallucinate invalid SQL syntax or attempt unsupported aggregations, causing the analytics workflow to crash repeatedly.

Identity vs. Key Separation

In basic auth systems, rate limits and metadata are tied directly to an API key. In Unkey, robust systems group keys under an Identity. An Identity (representing a user or tenant) holds shared metadata and rate limits, while multiple individual API keys map to that Identity.

When an LLM is tasked with "increasing the rate limit for a customer," it cannot just update the key. It must query the key, find the associated Identity, and apply the rate limit override to the Identity. Standard LLMs lack this domain-specific relational mapping without extensive prompt engineering.

Exposing Unkey Tools to AI Agents

Instead of building custom wrappers for every Unkey endpoint, Truto maps Unkey's REST endpoints into a standardized format and exposes them as function-calling schemas via the /tools endpoint.

Every integration on Truto represents how the underlying product's API behaves. Integrations define Resources (like keys, identities, ratelimits) and Methods (like List, Create, Set Permissions). Truto handles all authentication, base URLs, and structural mapping, returning a payload your LLM SDK natively understands.

By requesting the Unkey tools for a specific connected account, you instantly equip your agent with the capabilities required to manage your infrastructure.

Hero Tools for Unkey Automation

Below are the highest-leverage Unkey tools available via Truto. These go beyond basic CRUD operations and enable complex, autonomous infrastructure management.

unkey_analytics_get_verifications

This tool allows the agent to execute a SELECT SQL query against key verification analytics. It is incredibly powerful for monitoring traffic, detecting abuse, or building usage-based billing logic. The tool enforces that only SELECT queries are permitted.

"Write a SQL query to fetch all failed key verifications for API namespace 'api_123' from the last 24 hours, and execute it using the analytics verification tool. Summarize the top 3 reasons for failure."

create_a_unkey_key

Generates a new API key within a specified Unkey API namespace. The plaintext key is returned only once in this response, making it critical that the agent knows how to securely output or store this value immediately.

"Provision a new API key in the 'production' namespace for a new trial user. Return the plain text key so I can provide it to them securely, and do not log it anywhere else."

unkey_keys_verify

The core operation for testing if a key is valid. It verifies the key against permissions, rate limits, and usage quotas. Because Unkey hashes keys, this is the primary way an agent can check the live status of an auth token without seeing the plaintext secret.

"Take the provided raw API key string and run a verification check. Tell me if the key is enabled, how many credits are remaining, and what specific roles are attached to it right now."

unkey_keys_set_permissions

Replaces all direct permissions on an Unkey key in one atomic operation. This tool is vital for agentic access reviews or automated downgrades. The agent must be aware of the 30-second edge propagation delay when using this tool.

"Revoke all existing permissions on key 'key_abc123' and set its permissions to strictly 'read_only' and 'export_basic'. Acknowledge that this change may take up to 30 seconds to reflect globally."

unkey_ratelimit_set_override

Creates or updates a custom rate limit override for a specific identifier (like a user ID or IP address) within a namespace. Perfect for agents handling VIP customer support requests where a user needs a temporary quota bump.

"Customer 'tenant_889' is running a large data migration. Create a rate limit override for their identifier in the main namespace, increasing their limit to 500 requests per minute for the next 48 hours."

create_a_unkey_identity

Creates an identity entity to group multiple API keys together. This enables shared rate limits and pooled metadata across devices or environments for a single user.

"Create a new Unkey identity using the external ID 'usr_99x'. Once created, map the two newly provisioned API keys to this identity so they share the same rate limit pool."

To see the complete schema definitions and the full list of available operations, view the Unkey integration page.

Workflows in Action

Giving an LLM isolated tools is interesting, but chaining them together autonomously is where you solve real engineering problems. Here are two concrete workflows an agent can execute using the tools above.

1. Automated VIP Rate Limit Adjustment

Persona: Site Reliability Engineer / IT Admin

"Analyze the verification traffic for the last hour. If any identifier associated with our 'Enterprise' tier has hit their rate limit more than 50 times, automatically apply a temporary 20% rate limit override for that identifier and summarize the actions taken."

Step-by-step Execution:

1. The agent calls unkey_analytics_get_verifications with a SQL query filtering for HTTP 429 status codes over the past hour.
2. It parses the returned data to extract the specific identifier strings that exceeded the limits.
3. It calls unkey_ratelimit_set_override for the flagged identifiers, passing a newly calculated limit value (current limit + 20%).
4. The agent returns a structured summary to the Slack channel or ticketing system detailing which customer IDs were adjusted.

2. Secure Tenant Offboarding

Persona: SecOps Engineer

"We are offboarding tenant 'tenant_543'. Find their Unkey Identity, locate all associated API keys, replace all their permissions with a 'suspended' role, and verify the suspension is active."

Step-by-step Execution:

1. The agent calls get_single_unkey_identity_by_id using the external ID to fetch the internal Unkey Identity ID.
2. It calls unkey_apis_list_keys filtering by the retrieved Identity ID to get all active keys for that tenant.
3. For each key, it calls unkey_keys_set_roles to replace existing roles with the 'suspended' role.
4. The agent waits exactly 30 seconds to account for edge propagation.
5. It calls unkey_keys_verify on the hashes to confirm the permissions have officially updated before reporting the offboarding as complete.

Building Multi-Step Workflows

To build these autonomous workflows, your underlying code needs an execution loop that can fetch tools, pass them to the LLM, execute the requested functions, and handle API constraints - specifically rate limits.

Factual note on how Truto handles rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When Unkey (or any upstream API) returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec.

Your agent framework is strictly responsible for interpreting these headers and executing the backoff. If you do not handle this, your agent will hallucinate success or crash entirely.

Here is a conceptual flow of how the agent loop should operate:

graph TD
    A["Initialize Agent<br>(LangChain / Vercel AI)"] --> B["Fetch Unkey Tools<br>via Truto /tools API"]
    B --> C["Bind Tools to LLM"]
    C --> D["Receive User Prompt"]
    D --> E["LLM Decides Tool Call"]
    E --> F["Execute Tool via Truto Proxy"]
    F --> G{"HTTP Status?"}
    G -->|"200 OK"| H["Return Data to LLM"]
    G -->|"429 Rate Limit"| I["Read ratelimit-reset Header"]
    I --> J["Pause Execution (Backoff)"]
    J --> F
    H --> K{"Task Complete?"}
    K -->|"No"| E
    K -->|"Yes"| L["Final Output to User"]

Here is an abstracted TypeScript example demonstrating how to retrieve tools, bind them to a model, and handle the crucial 429 rate limit backoff loop manually. While this uses generic conceptual syntax, the pattern applies across all major frameworks.

import { ChatModel } from "your-llm-framework";
import { fetchTrutoTools } from "truto-sdk";
 
async function executeUnkeyWorkflow(prompt: string, accountId: string) {
  // 1. Fetch AI-ready tools from Truto for the Unkey account
  const unkeyTools = await fetchTrutoTools(accountId, {
    // Optional: Filter to specific methods if needed
  });
 
  // 2. Bind tools to the LLM
  const model = new ChatModel({ model: "gpt-4o" });
  const agent = model.bindTools(unkeyTools);
 
  let isComplete = false;
  let currentContext = prompt;
 
  // 3. Multi-step execution loop
  while (!isComplete) {
    const response = await agent.invoke(currentContext);
 
    if (response.toolCalls && response.toolCalls.length > 0) {
      for (const call of response.toolCalls) {
        try {
          // 4. Execute the tool via Truto
          const toolResult = await call.execute();
          currentContext += `\nTool Result: ${JSON.stringify(toolResult)}`;
        } catch (error) {
          // 5. CRITICAL: Handle HTTP 429 Passthrough from Truto
          if (error.status === 429) {
            // Read the standardized IETF headers Truto provides
            const resetTime = error.headers.get('ratelimit-reset');
            const waitMs = calculateWaitTime(resetTime);
            
            console.warn(`Rate limit hit. Agent sleeping for ${waitMs}ms`);
            await sleep(waitMs);
            
            // Append error to context so agent knows to retry
            currentContext += `\nTool Failed: Rate limited. Retrying now.`;
          } else {
            // Handle standard errors (400, 401, 500)
            currentContext += `\nTool Error: ${error.message}`;
          }
        }
      }
    } else {
      // No more tools called, agent has finalized the response
      console.log("Workflow Complete:", response.content);
      isComplete = true;
    }
  }
}
 
function calculateWaitTime(resetTimestamp: string) {
  // Logic to calculate milliseconds until resetTimestamp
  return 5000; // Example static backoff
}
 
function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

By controlling the execution loop locally, you retain complete authority over how rate limits, edge propagation delays, and errors are handled, while entirely avoiding the burden of maintaining the underlying API schemas.

Rethinking Infrastructure Automation

Connecting Unkey to AI agents shouldn't require your engineering team to spend weeks reading API docs, setting up cron jobs for token rotation, or debugging why a JSON payload failed validation due to a missing comma. By utilizing Truto's /tools endpoint, you abstract away the structural complexity of the API while retaining absolute control over the execution logic and rate limit handling.

Your engineers can focus on building resilient agentic loops and optimizing prompts, rather than writing boilerplate integration code.