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

  1. 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.
  2. 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.
  3. Your WorkOS administrator creates an API key for the environment in the WorkOS dashboard. The first valet-dedicated upgrade takes it from VALET_DEDICATED_WORKOS_API_KEY or 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.