Skip to main content

Configuring Allowlists

What You're Configuring​

An agent's allowlist defines which apps are permitted to send events to it. By managing allowlists, you enforce fine-grained access control over your agents.

Accessing the Allowlist​

  1. Go to the Agents page in the sidebar
  2. Click on the agent you want to configure (e.g., "Athena", "Klyve")
  3. Click the Allowlist tab

You'll see:

  • A list of currently allowlisted apps (if any)
  • An Add App button
  • Remove buttons next to each app

Adding Apps to an Allowlist​

Step-by-Step​

  1. Click Add App
  2. A modal appears showing all apps in your organization
  3. Select the app(s) you want to allowlist
  4. Click Confirm

The app(s) are now on the allowlist. They can immediately start sending events to this agent.

What Happens Next​

Once you add an app:

  • ✅ That app can send events to this agent
  • ✅ The app appears in the allowlist table
  • ✅ Other apps (not on the allowlist) are blocked
  • ❌ If no allowlist existed before, the agent is now restricted

Removing Apps from an Allowlist​

Step-by-Step​

  1. Find the app in the allowlist table
  2. Click the Remove button next to it
  3. Confirm the removal

The app is immediately removed from the allowlist.

What Happens Next​

Once you remove an app:

  • ❌ That app can no longer send events to this agent
  • ✅ If there are other apps on the allowlist, they continue to work
  • ✅ If this was the last app, the agent becomes open to all apps

Making an Agent Open Again​

If you want to allow all apps to reach an agent, remove all allowlist entries.

Option A: Remove One by One​

  1. Go to the agent's Allowlist tab
  2. Click Remove next to each app
  3. When the allowlist is empty, the agent is open

Option B: Clear All at Once​

Some dashboards may offer a Clear Allowlist or Make Open button:

  1. Click Clear Allowlist
  2. Confirm the action
  3. The agent is now open to all apps

Real-Time Effect​

Changes take effect immediately. There's no "deploy" or "save" step.

  • When you add an app to the allowlist, it can start sending events immediately
  • When you remove an app, it's blocked immediately
  • Apps currently sending events are not disconnected (but new events are rejected)

Event Log Indicators​

In the event log, look for the status field:

StatusMeaning
deliveredEvent was sent and agent replied
rejectedEvent was rejected because app is not allowlisted
failedAgent errored or timed out
pendingAgent is processing

If you see rejected status, check:

  1. Is the app on the agent's allowlist?
  2. Or did you just add the app (and the event was sent before the allowlist update)?

Monitoring Allowlist Changes​

Dashboard Audit Trail (Future Feature)​

In a future version, Relay may show an audit trail of allowlist changes:

  • When was app X added to agent Y?
  • Who made the change?
  • When was it removed?

For now, check your own records or review the event log for rejected events.

Detecting Unauthorized Access Attempts​

If you see repeated rejected events from the same app to the same agent, it could indicate:

  1. Configuration drift: The app's team forgot to allowlist
  2. New integration: A team added an integration without requesting allowlist access
  3. Intentional probing: Less likely, but monitor it

Review the event log regularly and reach out to app owners if you see unexpected rejection patterns.

Multi-Org Considerations​

If you have access to multiple organizations:

  • Each organization's agents have separate allowlists
  • Changes to Organization A's agent allowlist don't affect Organization B
  • You can switch organizations and manage each independently

Common Scenarios​

Scenario 1: General-Purpose Agent (Athena)​

You want Athena available to all apps.

Action: Leave the allowlist empty (no entries).

Result:

Athena (no allowlist)
  Portal  → ✓
  Flow    → ✓
  Studio  → ✓
  Any app → ✓

Scenario 2: Specialized Agent (Klyve)​

You want Klyve available only to Portal and Flow (code review and automation).

Action:

  1. Click Add App
  2. Select "Portal" and "Flow"
  3. Confirm

Result:

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

Scenario 3: Onboarding a New App​

You've built a new app ("Dashboard") and want to let it use Athena.

Action:

  1. Register the app in the dashboard
  2. Go to Athena's Allowlist tab
  3. Athena has no allowlist (open) → it already works
  4. If Athena was restricted, click Add App and select "Dashboard"

The new app can immediately start sending events to Athena.

Scenario 4: Restricting an Agent​

You've been running Klyve open to all apps, but now it's too expensive. You want to restrict it to Portal and Flow only.

Action:

  1. Go to Klyve's Allowlist tab
  2. Click Add App and select "Portal"
  3. Click Add App and select "Flow"
  4. Now Klyve has a 2-app allowlist

Result: Studio, Academy, and any other apps are immediately blocked from Klyve.

Scenario 5: Phasing Out an Agent​

You're deprecating an old agent ("OldBot") in favor of a new one ("NewBot"). You want to stop new integrations but allow existing ones to continue.

Action:

  1. Remove all apps from OldBot's allowlist
  2. OldBot is now only accessible to... no one
  3. Apps receive PERMISSION_DENIED errors
  4. After a transition period, deactivate OldBot

Result: All apps must switch to NewBot. You have time to coordinate the transition.

Best Practices​

1. Be Explicit About Allowlist Intent​

When you set up an agent:

  • No allowlist? Document that it's intentionally open
    • Example: "Athena is a general-purpose assistant available to all apps"
  • With allowlist? Document which apps are allowlisted and why
    • Example: "Klyve is restricted to Portal and Flow because it's specialized for code review"

2. Review Allowlists Regularly​

Once a month, review your agents' allowlists:

  • Are there apps that shouldn't be allowlisted?
  • Are there apps that should be added?
  • Do the allowlists match your team's understanding?

3. Communicate Changes​

If you restrict an agent or add a new one, notify the relevant app teams:

  • "Starting tomorrow, Klyve is only available to Portal and Flow"
  • "We've registered a new agent, ResearchBot, available to Portal"
  • "We're deprecating OldAgent in 2 weeks — please switch to NewAgent"

4. Monitor Event Log for Rejections​

Set up a regular review of rejected events:

  • Are there unexpected apps trying to reach restricted agents?
  • Do rejections correspond to known configuration changes?
  • Should any newly-rejected apps be re-allowlisted?

5. Document Your Configuration​

Keep a record of your allowlist decisions:

Agent: Athena (open)
  - General-purpose assistant
  - Available to all apps by design
  - No changes expected

Agent: Klyve (restricted)
  - Technical specialist for code review
  - Allowlisted: Portal, Flow
  - Last updated: 2026-04-05
  - Reason: Cost optimization, specialized use case

Troubleshooting​

"My app is being rejected even though I added it to the allowlist"​

  1. Verify the app is in the allowlist table
  2. Verify the agent is the one the app is trying to reach
  3. Check the event log — what's the exact error?
  4. Is the app's token valid and not rotated?
  5. Try restarting the app to ensure it's using the correct token

"I thought my agent was open, but now it's rejecting events"​

  1. Go to the agent's Allowlist tab
  2. Are there any apps listed? If yes, the agent is restricted
  3. Remove all apps to make it open again
  4. Or add the app that's being rejected

"I want to see which apps can reach this agent"​

  1. Go to the agent's Allowlist tab
  2. If the table is empty, the agent is open to all apps
  3. If the table has entries, only those apps can reach it

Summary​

  • Add apps to restrict an agent's access
  • Remove all apps to make an agent open
  • Changes take effect immediately — no deployment needed
  • Monitor the event log for rejected events
  • Document your decisions to keep your team aligned
  • Review allowlists regularly to ensure they match your intent

Next steps: