Managing Apps

What Is an App in Relay?

An app is any service that sends events to Relay to request AI agent responses. Examples:

• Portal — your project management app
• Flow — your workflow engine
• Studio — your code editor
• Academy — your learning platform
• Custom integration — anything else connecting to Relay

Each app gets a unique token (rlk_...) for authentication. The app's backend uses this token to connect to Relay's WebSocket and send events.

Registering a New App

To register an app:

1. Go to the Apps page in the dashboard sidebar
2. Click Register New App
3. Fill in the app details:
   • App Name — display name (e.g., "Portal", "Flow", "My Custom Service")
   • App ID — URL-safe slug (e.g., "portal", "flow", "custom-service")
     • Must be unique within your organization
     • Lowercase letters, numbers, hyphens only
     • Cannot be changed after creation
4. Click Register

Relay creates the app and generates an app token.

App Tokens

When you register an app, Relay generates a unique token that looks like:

rlk_portal_x8k2m9p2d7q4v1r9z5k3j8h2...

Token Security

This token is shown exactly once. After you leave the page, you cannot retrieve it again from Relay. You must store it immediately.

Where to store your token:

• Environment variables: RELAY_APP_TOKEN=rlk_portal_... in your .env file
• Secrets manager: AWS Secrets Manager, HashiCorp Vault, etc.
• Config file: Never in version control — always in .env.local or .gitignore

Token Format

rlk_{app_id}_{random_string}

• rlk_ — prefix identifying this as an app token
• {app_id} — your app's ID (e.g., "portal")
• {random_string} — cryptographically random suffix

Relay stores only a bcrypt hash of the full token in the database. The plaintext is never logged or recoverable.

App Detail Page

Click an app name to view its detail page:

Connection Status

Live indicator showing whether the app is currently connected to Relay:

• Connected — app's WebSocket is open and authenticated
• Disconnected — app is not connected
• Last Connected — timestamp of the most recent connection

This helps you monitor if your app integration is running.

Configuration

Field	Value	Notes
App ID	portal	URL-safe identifier
Organization	Acme Corp	The organization that owns this app
Created	2026-04-05 14:32 UTC	Registration date
Status	Active / Inactive	Whether the app can connect

Event History

A table showing recent events from this app:

Event ID	Agent	Thread	Status	Latency	Timestamp
evt_k9p2	athena	task-123	delivered	2300ms	2026-04-07 10:15
evt_k8m1	klyve	job-456	delivered	1800ms	2026-04-07 10:12
evt_k7l5	athena	task-123	failed	—	2026-04-07 10:05

Click an event to see its full details (payload, reply, timeline).

Agents This App Can Reach

A list of agents this app is allowlisted for. If there's no allowlist restriction, this shows all agents in the organization.

Deactivating an App

If an app is no longer active (you've shut down a service, for example), you can deactivate it:

1. Open the app's detail page
2. Click Deactivate App
3. Confirm the action

A deactivated app cannot authenticate to Relay's WebSocket. If someone tries to use its token, the connection will be rejected.

You can reactivate the app later if needed.

Use Cases for Deactivation

• Maintenance: Shut down an app temporarily for updates
• Deprecation: Phase out an old version of an app
• Cleanup: Remove test apps from production

Token Rotation

If you suspect a token has been compromised, or if you want to rotate tokens periodically:

1. Open the app's detail page
2. Click Rotate Token
3. Relay issues a new token (shown immediately — copy it!)
4. The old token has a 1-hour grace period

The Grace Period

After you rotate an app's token:

• ✅ New token works immediately
• ✅ Old token still works for 1 hour (allows for gradual rollout)
• ❌ After 1 hour, old token is completely invalid

This gives you time to update your app's .env file without disrupting active connections.

How to Rotate in Practice

1. In Relay dashboard: Click "Rotate Token"
2. Copy the new token
3. Update your app's .env file: Replace the old token with the new one
4. Restart your app (or it will use the new token on next deployment)
5. Verify connection: Check the connection status on the app detail page

Within the 1-hour grace period, your old connections will gracefully close and new ones will use the new token.

Monitoring

Connection Uptime

The connection status shows whether your app is currently connected. If your app disconnects:

1. Check your app logs for WebSocket errors
2. Verify the token is correct (compare with Relay dashboard)
3. Verify your firewall allows outbound WSS connections
4. Check if the token has been rotated (and if the app is using the new one)

Event Success Rate

On the app detail page, you can see recent events:

• Status "delivered": Event was successfully forwarded to the agent
• Status "failed": Agent sent an error or timed out
• Status "pending": Event is waiting (agent offline or processing)
• Status "rejected": App sent the event to a non-allowlisted agent

If you see many rejected events, check the agent's allowlist.

Best Practices

1. Secure Your Token

• Never commit tokens to version control
• Never share tokens via email or chat
• Store in .env files (gitignored)
• Use a secrets manager in production

2. Use Descriptive Names

When registering an app, use a name that's clear to your team:

• ✅ "Portal" — clear
• ✅ "Flow Workflow Engine" — descriptive
• ❌ "MyApp" — ambiguous
• ❌ "Test" — will be confusing later

3. Monitor Connection Status

• Check the dashboard regularly to ensure your app is connected
• Set up alerts if connection status drops (integrate with your monitoring system)
• If you deploy a new version, verify it connects to Relay

4. Rotate Tokens Periodically

Even if your token hasn't been compromised, rotate it every few months as a security best practice.

5. One Token Per App

Each app should have exactly one token. Don't share tokens between apps. If you're running multiple instances of the same app (load-balanced), they all use the same token — but each instance maintains its own WebSocket connection.

Summary

• Register apps in the dashboard
• Store tokens immediately — they're shown only once
• Monitor connection status to ensure your app is integrated
• Rotate tokens if compromised or periodically
• Deactivate apps when they're no longer active
• Check event history to verify integration is working

Next steps:

• Configure allowlists for your agents
• Connect your app via WebSocket
• Follow integration steps for your language