Security and credentials

How Agent Studio handles credentials and security for different tool types.

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

Different tool types use different credential handling strategies. This page explains how Agent Studio stores and uses credentials securely.

Algolia Search and Algolia Recommend

For these built-in tools:

• Use your Algolia application credentials from your account settings

• Always use Search API keys, never Admin API keys

• Credentials are automatically encrypted at rest in Agent Studio’s database

• You can restrict Search API keys by:

  • Index names
  • Query parameters
  • TTL (time to live)
  • IP addresses (not recommended for agent use cases)

User-restricted access with secured API keys

The Algolia Search tool reuses the API key your app sends when it interacts with the agent. When you use secured API keys, the agent inherits the same access control restrictions, ensuring users only see the data they’re authorized to access.

How user-restricted access works

1. Your app generates a secure API key for the current user
2. You pass this key when making completion requests to Agent Studio
3. The Algolia Search tool automatically uses this secured key for all searches
4. The agent can only retrieve records matching the user’s permissions

For example, to restrict by user ID:

JavaScript

// Backend: generate secure API key for current user
const securedApiKey = client.generateSecuredApiKey({
  parentApiKey: "ALGOLIA_SEARCH_API_KEY",
  restrictions: {
    filters: `userId:${currentUser.id}`,
  },
});

// Frontend: pass secure API key to agent
const response = await fetch(
  `https://generative-ai.algolia.com/agent-studio/1/agents/${agentId}/completions`,
  {
    method: "POST",
    headers: {
      "X-Algolia-Application-Id": "ALGOLIA_APPLICATION_ID",
      "X-Algolia-API-Key": securedApiKey, // Use secured key
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Show my orders" }],
    }),
  },
);

Benefits

• Consistent security: agent searches respect the same access rules as your app
• Multi-tenant support: different users see different data without separate agents
• Row-level security: restrict by user ID, organisation, region, or any indexed attribute
• No configuration changes: works automatically with existing secured API key

For more information, see User-restricted access to data.

MCP tools

• Agent Studio automatically encrypts authorization headers at rest (for example, Authorization: Bearer TOKEN)
• The API redacts authorization headers by default when you retrieve agent configurations
• Agent Studio stores custom (non-authorization) headers in plain text but doesn’t expose them in logs
• You can configure up to 10 headers per MCP server

Client-side tools

• Agent Studio doesn’t store any credentials
• Your app manages authentication and runs tools in the user’s security context
• Agent Studio never sees or stores user authentication tokens

MCP runtime header overrides

For multi-tenant apps where each user has their own API credentials:

Configuration (one-time)

JSON

{
  "type": "mcp_tools",
  "name": "crm_api",
  "url": "https://api.crm.example.com/mcp",
  "headers": {
    "Authorization": "Bearer SYSTEM_DEFAULT_TOKEN"
  }
}

Runtime override (per user)

Pass custom headers when creating a completion:

JSON

{
  "messages": [...],
  "algolia": {
    "mcpServers": {
      "crm_api": {
        "headers": {
          "Authorization": "Bearer user_alice_token_xyz"
        }
      }
    }
  }
}

Security guarantees

• Runtime headers are ephemeral and never persisted by Agent Studio
• Only MCP servers configured in the agent can receive header overrides
• URL and transport can’t be overridden (prevents redirection attacks)
• Headers aren’t logged or stored in any system logs

See also

• Tools overview
• MCP tools
• API keys