Authentication

The platform uses Amazon Cognito for sign-in. You have three ways to wire it up:

Mode	Admins and end users	Sign-up flow
Default (split pools)	Two separate Cognito pools (one each)	Sign up separately on / and /try/
Unified (one pool)	A single Cognito pool used for both	One sign-up; same account works on both surfaces
External pool (e.g., RainMaker)	Your existing Cognito pool replaces the auto-created ones	Users already signed in to your app land in agents directly

You set this up on the Deployment Management Dashboard → Configuration tab.

Mode 1 — Default (split pools)

This is what you get out of the box.

• Admins sign up at https://<your-domain>/ (the Manage agents surface).
• End users sign up at https://<your-domain>/try/ (the Try now surface).
• The two are independent — same email can be both, but you create accounts twice.

You don't need to change anything for this mode.

Mode 2 — Unified (one pool)

You want one sign-up to cover both sides.

1. Open the Deployment Management Dashboard.
2. Configuration tab → User Authentication (Cognito):
   • User Pool ID → use the auto-created admin pool (or vice versa). Either pool can serve both, as long as both sections point to the same pool.
   • User Pool Client ID → matching client.
   • User Pool Domain → matching domain.
3. Admin Authentication (Cognito) → fill in the same values as User Authentication.
4. Save Configuration.
5. Go to the Updates tab and click Update Stack. This step is required to apply your saved configuration to the backend stack. The update usually takes about 30 minutes.
6. Update the pool's callback / sign-out URLs in the Cognito console — see Callback URLs below. Use both / and /try/ URLs.

After this, a single account works on both surfaces.

Mode 3 — External pool (e.g., RainMaker)

You already have a Cognito pool (your RainMaker user pool, an existing internal IdP, etc.) and want the agents platform to reuse it. Existing users don't have to sign up again — they just sign in.

This is what Espressif's production deployment does to share users with the ESP RainMaker Home mobile app. Devices and apps that already hold a RainMaker access token can use the same token against the agents API directly.

Steps

1. Note your existing pool's ID, App Client ID, and Cognito Domain.
2. Open the Deployment Management Dashboard.
3. Configuration tab:
   • Paste those values into User Authentication (Cognito).
   • Paste the same values into Admin Authentication (Cognito) (unless you want admin separation).
4. Save Configuration.
5. Go to the Updates tab and click Update Stack. This step is required to apply your saved configuration to the backend stack. The update usually takes about 30 minutes.
6. Update the pool's callback / sign-out URLs in Cognito (see below).

After this:

• The default admin and end-user pools created at deploy time are no longer used.
• Anyone with a RainMaker (or your IdP) account can sign into agents directly.
• Their access token works against the agents API too — handy for devices and integrations.

Callback / sign-out URLs

After pointing at a Cognito pool — yours or the auto-created one — you must register the dashboards' URLs as Allowed callback URLs and Allowed sign-out URLs on the pool's app client. Cognito refuses sign-in / sign-out otherwise.

Replace <deployment-prefix> below with your deployment's actual 10-character prefix (e.g., bxmqxnlxtx).

Allowed callback URLs

https://<deployment-prefix>.evaluation.esp-private-agents.com/
https://<deployment-prefix>.evaluation.esp-private-agents.com/try/
https://<deployment-prefix>.evaluation.esp-private-agents.com/oauth/callback
https://<deployment-prefix>.evaluation.esp-private-agents.com/try/oauth/callback

Allowed sign-out URLs

https://<deployment-prefix>.evaluation.esp-private-agents.com/
https://<deployment-prefix>.evaluation.esp-private-agents.com/try/

If you're using a Custom Domain, use that domain instead of the evaluation.esp-private-agents.com host.

Where to set these in Cognito

AWS Console → Cognito → select the user pool → App clients → select the client → Login pages → Edit → add the URLs.

What goes in which pool

Scenario	Callback URLs	Sign-out URLs
Admin pool only	https://<deployment-prefix>…/ and …/oauth/callback	https://<deployment-prefix>…/
End-user pool only	https://<deployment-prefix>…/try/ and …/try/oauth/callback	https://<deployment-prefix>…/try/
Unified or external pool	Both (admin + end-user) URLs above	Both

Choosing a mode

You want…	Pick
Quickest path; small team	Default (split pools)
One sign-up to cover everything	Unified (one pool)
Reuse an existing user base / IdP	External pool
Devices already on RainMaker tokens	External pool (RainMaker)

Common gotchas

Symptom	Likely cause
Sign-in redirects to "Bad request"	Callback URL not registered on the Cognito app client.
Sign-out lands on a blank page	Sign-out URL not registered.
Admin and user accounts conflict	You unified pools but didn't add both sets of callback URLs.
External pool but admin features missing	Group / role mapping in your external pool isn't configured to grant admin scope.
Configuration is not applied	Saved changes on the Configuration tab only take effect after a stack update. Go to the Updates tab and click Update Stack.

What's next

• Custom domain
• Operations