Dashboard to Server Connection

Connect the ACE dashboard (ace3-ai.com) to your ACE server, wherever it runs

The Problem

Why you need the API key bridge

The ACE dashboard uses cloud JWTs (signed with the cloud backend's secret), but your ACE server has a different JWT secret. This causes 401 Unauthorized errors when the dashboard tries to call your server directly.

Without API Key Bridge:

Dashboard authenticates with cloud backend (JWT signed with cloud secret)
Dashboard calls your ACE server with cloud JWT
Your ACE server rejects it - different JWT secret!

With API Key Bridge:

You generate an API key on your ACE server
API key is stored securely in the cloud backend
Dashboard uses API key to authenticate - works everywhere!

Deployment Scenarios

ACE works wherever your server runs

Scenario	ACE Server Location	Setup Required
Local Development	localhost:7777	Automatic with `ace login`
On-Premises	ace.company.com	Set `ACE_CLOUD_JWT_SECRET`
Cloud-Hosted	my-ace.run.app	Set `ACE_CLOUD_JWT_SECRET`

Setup Instructions

Choose your deployment scenario

Automatic Setup (Recommended)

For local development, connection is configured automatically during login.

1. Install ACE

2. Login and start server

Dashboard connection is configured automatically during login.

3. Open Dashboard

Visit ace3-ai.com/dashboard - it will auto-connect to your local server.

How It Works

The API Key Bridge architecture

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Developer     │     │   Your ACE Server    │     │   Cloud Backend │
│   Laptop        │     │   (on-prem/cloud)    │     │   (ace3-ai.com) │
└────────┬────────┘     └──────────┬───────────┘     └────────┬────────┘
         │                         │                          │
   1. ace login ──────────────────────────────────────────────▶ OAuth
         │                         │                          │
         ◀──────────────────────────────────────── cloud JWT ──┘
         │                         │
   2. ace connect --server https://ace.company.com
         │                         │
         │── Generate API key ─────▶ (validates cloud JWT
         │                         │  via ACE_CLOUD_JWT_SECRET)
         │                         │
         ◀─── api_key: ace_sk_... ─┘
         │                         │
   3. Register with cloud ─────────────────────────────────────▶ stores
         │                         │                          │ encrypted
         │                         │                          │
   4. Dashboard fetches API key ◀──────────────────────────────┘
         │                         │
   5. Dashboard calls your server ─▶ (uses API key, not JWT)
         │                         │
         ◀─── data ────────────────┘

OAuth Login: You authenticate with ace3-ai.com and receive a cloud JWT.

API Key Generation: Your ACE server validates the cloud JWT (using ACE_CLOUD_JWT_SECRET) and generates an API key.

Registration: The API key is encrypted and stored in the cloud backend.

Dashboard: When you open the dashboard, it fetches your API key from the cloud.

API Calls: Dashboard authenticates with your ACE server using the API key (not JWT).

Team/Organization Setup

Share a connection with your team

For teams using a shared ACE server, an admin can configure a single connection that all organization members inherit.

Shared Organization Key

Admin deploys ACE to company server
Admin runs: ace api-key create --description "Team Dashboard"
Admin enters URL + API key in dashboard settings
Admin enables "Share with organization" toggle
All org members automatically use the shared connection

Benefits: Simpler onboarding - new team members don't need to configure anything. Single point of management for IT admins.

Environment Variables

Configuration for remote ACE servers

On Remote ACE Servers

Variable	Required	Description
ACE_CLOUD_JWT_SECRET	Yes*	Cloud backend's JWT secret for validating cloud tokens during `ace connect`
ACE_JWT_SECRET	Yes	Your server's own JWT secret
ACE_DATABASE_ENCRYPTION_KEY	Yes	Fernet key for encrypting stored data

*Required for automatic ace connect flow. Not needed if using manual API key setup.

CLI Commands

Commands for managing connections

ace connect

Set up dashboard connection to your ACE server.

Connect to local server (default):

Connect to remote server:

Connect to cloud-hosted server:

ace disconnect

Remove dashboard connections.

Interactive prompt to select which connection to remove.

Troubleshooting

Common issues and solutions

"Authentication failed" on ace connect

Cause: Remote server doesn't have ACE_CLOUD_JWT_SECRET configured.

Fix: Set ACE_CLOUD_JWT_SECRET on your remote server, OR use manual setup (generate API key on server, enter in dashboard).

Dashboard shows "Offline" but server is running

Cause: No connection registered, or API key expired.

Fix: Run ace connect to re-establish connection, or manually add connection in dashboard settings.

"API key is invalid or expired"

Cause: The stored API key was revoked or server was reset.

Fix: Run ace connect to generate new API key, or manually create new API key and update in dashboard.

Security Considerations

How your connections are protected

API keys are encrypted

Stored at rest using Fernet encryption (AES-128).

Cloud JWT acceptance is limited

Cloud JWTs are only accepted for the API key generation endpoint, not for regular API calls.

Organization sharing

Team members can use a shared connection without seeing the API key.

Revocation support

API keys can be revoked at any time via CLI or dashboard.

Next Steps

Configure Connection in Settings Getting Started Guide API Keys & BYOK Setup Deployment Guide