Authentication

IAS uses two separate authentication planes: one for humans interacting with the Console UI, and one for machines (workers 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.

Human Auth (Console UI)

The IAS Console 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 Tokens (Recommended for CI/CD)

For automation and CI/CD pipelines, use a service token instead of device login. Service tokens are non-interactive and designed for headless environments.

Setup:

1. Generate a random token value and set it as a Convex environment variable:

   IAS_CONTROL_PLANE_SERVICE_TOKEN=your-random-secret

   This variable supports comma-separated values for token rotation -- you can add a new token before removing the old one:

   IAS_CONTROL_PLANE_SERVICE_TOKEN=new-token,old-token

2. Configure the worker with the token. Either pass it via environment variable:

   export IAS_CONTROL_PLANE_SERVICE_TOKEN="your-token-here"

   Or set it in the worker configuration file (~/.ias/worker.json):

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

Service tokens are workspace-scoped. The worker sends the token as a bearer token in the Authorization header, and the control plane validates it against the stored value.

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 three 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 token -- Compares the bearer token against the IAS_CONTROL_PLANE_SERVICE_TOKEN environment variable (supports multiple comma-separated tokens).
3. 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 service tokens only 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