Operator guide for Valet Dedicated 0.10.1
How WorkOS works
People sign in to a Valet Dedicated installation through WorkOS, which connects to your identity provider. This page says who runs each part, what you configure, and how to ask for a change.
Who does what
The WorkOS environment for your installation
- Who
- Valet creates and administers it
The environment's sign-in settings
- Who
- Valet sets them
The connection to your identity provider (SSO)
- Who
- You, through the WorkOS Admin Portal
Verification of your email domains
- Who
- You, in the Admin Portal
The WorkOS API key
- Who
- Your WorkOS administrator creates it. Nobody at Valet sees it.
Valet keeps ownership of the environment. It invites your WorkOS administrator to the environment so that person can create the API key.
What Valet sets
Valet configures the environment so that:
- only SSO through your identity provider signs people in. Password, magic link, and social sign-in are off;
- the dashboard's redirect addresses work, so sign-in and sign-out return to
https://dashboard.<apex>; and - MCP clients can sign in at
https://api.<apex>/mcp.
Valet sends you three things when the environment is ready: the Admin Portal
link, the environment's client ID, and its AuthKit domain. The client ID and
the AuthKit domain are identifiers, not secrets. You pass them to the module
as the workos input.
What you configure
- Open the Admin Portal link as your identity provider's administrator and follow its steps to connect your identity provider. The link expires soon after Valet creates it. Ask Valet for a new one if it has expired.
- In the Admin Portal, verify each email domain with the DNS TXT record the portal gives you. Until a domain is verified, nobody on it can sign in.
- Your WorkOS administrator creates an API key for the environment in the
WorkOS dashboard. The first
valet-dedicated upgradetakes it fromVALET_DEDICATED_WORKOS_API_KEYor a prompt, and stores it in Secrets Manager. The module never holds the key.
Prepare gives the same steps in order.
What happens at sign-in
A person opens https://dashboard.<apex> and signs in. WorkOS sends them to
your identity provider. When your provider admits them, WorkOS returns them
to the dashboard. The first sign-in adds the person to the home org. See
Connect your people.
The installation records each sign-in, and each refused attempt, as a
session.create event in the audit log.
Impersonation
Impersonation is off. WorkOS can let its operators start a session as one of your users. The installation refuses every such session, so no one at Valet can sign in as one of your people.
valet-dedicated check reports the setting. It prints impersonation is off
when the running dashboard enforces it, and fails when the dashboard's task
definition lacks the empty AUTH_IMPERSONATOR_ALLOWED_DOMAINS value. The fix
is to re-apply the module and run upgrade. Each refused attempt is an
event in the audit log: session.impersonate with the outcome deny.
Ask for a change
Valet administers the environment, so Valet makes changes to it. Email support@valet.dev, as in Get help. Say which installation and what you need, for example:
- a new Admin Portal link, because yours expired;
- another email domain for your people;
- a change of your WorkOS administrator; or
- a sign-in that fails for everyone. For this, attach a support bundle and say what the person sees.
Never email the WorkOS API key or a password. See Get help.
If a sign-in fails, see Troubleshoot.