Skip to main content

Agent Allowlists

How Allowlists Work​

An allowlist is a list of apps that are permitted to send events to a specific agent. By default, agents are open — any app in your organization can reach them. If you want to restrict access, you add apps to the agent's allowlist.

Once an allowlist exists for an agent, only allowlisted apps can send events to it. All other apps are rejected.

Open vs. Restricted​

Open Agent (No Allowlist)​

If Athena has no allowlist entries:

Athena (open)
  Portal  → Athena ✓ (allowed)
  Flow    → Athena ✓ (allowed)
  Studio  → Athena ✓ (allowed)
  Any registered app → Athena ✓ (allowed)

All apps in the organization can reach Athena.

Restricted Agent (With Allowlist)​

If you add Portal and Studio to Athena's allowlist:

Athena (restricted)
  allowlist: [Portal, Studio]

  Portal  → Athena ✓ (on allowlist)
  Studio  → Athena ✓ (on allowlist)
  Flow    → Athena ✗ (rejected: not on allowlist)
  Any other app → Athena ✗ (rejected)

Only Portal and Studio can reach Athena.

Real-World Examples​

Example 1: Athena (General Assistant)​

Athena should be available to all apps. No allowlist needed.

Athena (no allowlist)
  Portal  → ✓
  Flow    → ✓
  Studio  → ✓
  Academy → ✓

Example 2: Klyve (Technical Workflows)​

Klyve is specialized for code review and should only be available to Portal and Flow.

Klyve (allowlist: Portal, Flow)
  Portal  → ✓ (on allowlist)
  Flow    → ✓ (on allowlist)
  Studio  → ✗ (not on allowlist)
  Academy → ✗ (not on allowlist)

Example 3: Internal Research Agent​

You have a proprietary research agent that should only be used by Portal's advanced features.

ResearchBot (allowlist: Portal)
  Portal  → ✓ (on allowlist, can use for research)
  Flow    → ✗ (not allowed)
  Studio  → ✗ (not allowed)

What Happens When Rejected?​

If an app tries to send an event to a non-allowlisted agent:

  1. Relay receives the event
  2. Relay checks the allowlist
  3. App is not on the allowlist
  4. Relay sends an error back to the app:
{
  "type": "error",
  "event_id": "evt_k9p2m",
  "agent_id": "athena",
  "error": "App not allowlisted for this agent",
  "code": "PERMISSION_DENIED"
}

The event is not forwarded to the agent. It's logged as rejected in the event log, so you can see attempted unauthorized access.

Managing Allowlists​

Via Dashboard​

  1. Go to Agents in the sidebar
  2. Click the agent you want to configure (e.g., "Athena")
  3. Go to the Allowlist tab
  4. Click Add App
  5. Select the app from the list
  6. Click Confirm

To remove an app from the allowlist:

  1. Find the app in the allowlist table
  2. Click the Remove button
  3. Confirm the action

Making an Agent Open Again​

If you've restricted an agent and want to make it open again:

  1. Go to the agent's Allowlist tab
  2. Click Remove next to each app
  3. Once all apps are removed, the agent is open

Alternatively, there may be a Make Open button that removes the entire allowlist at once.

Allowlist is Organization-Scoped​

Allowlists are per-organization. If you have access to multiple organizations:

  • Organization A's allowlist is separate from Organization B's
  • Removing an app from allowlist in Organization A doesn't affect Organization B
  • Each organization manages its own agent restrictions

Discovery and Allowlists​

When an app calls the discovery endpoint, Relay returns only the agents that app is allowed to reach:

{
  "type": "discover"
}

Response:

{
  "type": "agents",
  "agents": [
    {
      "agent_id": "athena",
      "name": "Athena",
      "description": "Personal EA"
    },
    {
      "agent_id": "klyve",
      "name": "Klyve",
      "description": "Technical workflows"
    }
  ]
}

If Portal is not allowlisted for Klyve, Klyve won't appear in Portal's discovery response. This means:

  • ✅ Apps can auto-discover which agents they can reach
  • ✅ No "permission denied" surprises at runtime
  • ✅ UIs can show only available agents

Best Practices​

1. Start Open​

Create new agents without an allowlist. Let them be accessible to all apps. You can restrict later if needed.

2. Restrict Only When Necessary​

Add allowlist entries only when:

  • An agent is specialized and shouldn't be used by all apps
  • An agent has high costs and you want to limit usage
  • An agent is experimental and not ready for all apps

3. Document Your Decisions​

In agent descriptions or internal notes, explain why an agent has or doesn't have an allowlist:

Athena: No allowlist (open to all apps)
  → General-purpose assistant

Klyve: Allowlist [Portal, Flow]
  → Technical specialist; limited to code review workflows

ResearchBot: Allowlist [Portal]
  → Proprietary research; not yet available to other apps

4. Monitor Rejected Events​

In the event log, filter for rejected events. If you see apps repeatedly trying to reach an agent they're not allowlisted for, that might indicate:

  • Misconfiguration in the app
  • An app that should be allowlisted but isn't
  • Intentional probing (less likely, but monitor it)

Summary​

  • Open by default: Agents are accessible to all apps unless restricted
  • Restrict by adding allowlist entries: Add apps to the allowlist to restrict access
  • Only allowlisted apps can reach restricted agents: Other apps get permission errors
  • Managed in the dashboard: Add/remove apps via the agent's Allowlist tab
  • Affects discovery: Apps only see agents they're allowlisted for

This gives you fine-grained control over agent access without complex permission systems.