Authentication

IAS uses two separate authentication planes: one for humans interacting with the Console UI, and one for machines (local execution commands and automation) communicating with the control plane API. This separation reflects the different trust models -- browser-based sessions for humans, bearer tokens for headless processes.

This page is current-implementation oriented. The product North Star is one governed local runtime, but the current framework still exposes worker and runner command names.

Human Auth (Console UI)

The IAS Hub uses Clerk as its identity provider. Clerk handles user registration, login, session management, and SSO.

When a user signs in to the Console:

1. Clerk authenticates the user (email/password, SSO, or social login)
2. Convex receives the authenticated identity via a JWT
3. Convex functions enforce workspace membership on every query and mutation

All Console UI operations are scoped to the user's workspace membership and role. Roles include owner, admin, member, and viewer, with permissions enforced at the backend level.

Machine Auth (Workers and Automation)

Workers are headless CLI processes that do not have a browser session. They communicate with the Console backend via the control plane HTTP API, and they need a token to do so. IAS provides two mechanisms for worker authentication, plus a dev-only fallback.

Device Login (Recommended for Developers)

Device login lets a developer authenticate their machine once using a browser, after which the CLI stays logged in. This is the recommended approach for development teams because it ties access to a real user identity and workspace membership.

Flow:

1. Run the login command:

   ias auth login

2. The CLI creates a short-lived device session in Convex and opens your browser to the Console's device approval page (/auth/device)

3. Sign in with Clerk (email, SSO, or social login) and click Approve worker

4. The CLI polls for approval, receives a bearer token, and stores it locally

Token storage:

The token is saved at ~/.ias/auth.json, keyed by {convexDeploymentUrl, workspaceSlug}. This means:

• You can be authenticated to multiple workspaces simultaneously on the same machine
• The same login is reused across all repositories mapped to that workspace
• If controlPlane.workspaceSlug is not set in your worker config yet, the browser approval flow will ask you to pick a workspace and the CLI writes the slug back automatically

Token lifecycle:

• Device sessions expire after approximately 5 minutes (the browser approval window)
• Worker tokens are valid for approximately 30 days
• Run ias auth status to check your current authentication state (token, expiry, workspace)
• Run ias auth logout to revoke and remove your token
• Tokens can be revoked individually without rotating a shared secret

Service-Principal Tokens (Recommended for CI/CD)

For production runtimes, shared environments, and CI/CD pipelines, use a Hub-minted workspace-scoped service-principal token instead of device login. Service-principal tokens are non-interactive, attributable to one workspace/principal, and designed for headless environments.

Setup:

1. Mint a service-principal token in Hub for the target workspace.

2. Configure the worker with the token in ~/.ias/worker.json:

   {
     "controlPlane": {
       "httpServiceToken": "your-token-here"
     }
   }

The worker sends the token as a bearer token in the Authorization header, and the control plane validates it against the hashed token record for that workspace.

IAS_CONTROL_PLANE_SERVICE_TOKEN on the Hub deployment is a broad local/admin fallback only. It is rejected unless the deployment explicitly sets IAS_CONTROL_PLANE_ALLOW_GLOBAL_TOKEN=true; do not use it for production, shared runtimes, or CI/CD. Existing deployments that still use IAS_CONTROL_PLANE_ALLOW_GLOBAL_SERVICE_TOKEN must rename that Convex env var before rollout because Convex rejects the old name for exceeding the env-var length limit.

Dev-Only Mode

For local development, you can bypass authentication entirely:

IAS_DEV_ALLOW_UNAUTH=true

Set this as a Convex environment variable. When enabled, the control plane API accepts unauthenticated requests without requiring a bearer token.

This must never be used in production or shared deployments. It is strictly for local development convenience when you need to iterate quickly on worker logic without managing tokens.

How Workers Authenticate

All worker communication with the Console happens over the control plane HTTP API. The base URL follows the pattern:

https://<deployment>.convex.site/control-plane/...

Workers send their token as a standard Bearer token in the Authorization header:

Authorization: Bearer <token>

The control plane validates the token through one of four paths:

1. User token -- Hashes the bearer token and looks up the corresponding device auth record. Resolves the workspace ID and user identity, then verifies workspace membership.
2. Service-principal token -- Hashes the bearer token and validates it against the workspace-scoped service-principal token record.
3. Global service-token fallback -- Compares the bearer token against IAS_CONTROL_PLANE_SERVICE_TOKEN only when IAS_CONTROL_PLANE_ALLOW_GLOBAL_TOKEN=true is set on the Hub deployment.
4. Dev unauth -- If IAS_DEV_ALLOW_UNAUTH=true is set, skips authentication entirely.

Write operations additionally verify that the authenticated identity has appropriate permissions for the target workspace.

Auth Commands

Configuration Reference

Worker configuration lives at ~/.ias/worker.json (never committed to any repository). Key auth-related fields:

{
  "controlPlane": {
    "convexDeploymentUrl": "https://your-deployment.convex.cloud",
    "workspaceSlug": "your-workspace",
    "consoleAppUrl": "https://console.example.com",
    "httpServiceToken": "(optional, for CI/CD)"
  }
}

Auth tokens are stored separately at ~/.ias/auth.json, keyed by deployment URL and workspace slug.

The ias setup command creates and populates the worker configuration file interactively. For manual setup, see Install & Bootstrap.

Multi-Developer Guidance

When multiple developers share a workspace:

• Each developer runs their own local worker with their own ~/.ias/worker.json (never committed)
• Prefer device login for developer machines so access is tied to individual identity
• Use workspace-scoped service-principal tokens for shared automation and CI/CD pipelines
• Configure a repo allowlist in each worker config (repos.mappings[]) so workers only claim jobs for repositories they can actually operate on locally
• Tokens can be revoked per-developer without affecting the rest of the team