SSO device flow

The SSO device flow lets an employee at a Google Workspace or Okta org run a CLI command, approve it in their browser via a real IdP sign-in, and receive a short-lived sk-proxy-… key scoped to their identity. It’s a full RFC 8628 OAuth 2.0 Device Authorization Grant implementation — no admin has to manually mint or share credentials.

When to use it

Use SSO device-flow keys for:

Interactive CLI tools — anywhere a developer runs a local command that needs a RouteShift key.
Notebooks and one-off scripts — short-lived credentials that auto-expire.
Onboarding — new hires get a working key the moment they can sign in to your IdP, with no admin ticket.

Stick with regular virtual keys for:

Production services and CI — long-lived, machine-owned credentials with per-key budgets and model allowlists.
Shared agents — keys that outlive any one employee.

How the flow works

Employee runs the CLI

Their local tool calls POST /oauth/device/code with the employee’s email. RouteShift looks up the team by email domain (home-realm discovery) and returns a device_code, an 8-character user_code, and a verification_uri.

Employee approves in the browser

The CLI prints the code and opens https://proxy.routeshift.io/oauth/device/verify. The employee signs in to Google Workspace or Okta, sees the code they were shown, and clicks Approve.

RouteShift verifies the identity

The IdP redirects back to /oauth/device/callback with an authorization code. RouteShift exchanges it for an ID token, validates the issuer, audience, nonce, and email domain, then marks the authorization approved.

CLI receives a key

The CLI has been polling POST /oauth/device/token with the device_code. Once approved, it receives a fresh sk-proxy-… token valid for 8 hours.

Keys minted this way are stamped with metadata.issued_via = "sso_device_flow" and metadata.email = "<verified-email>". Only one live SSO key is allowed per (team, email) pair — a second flow for the same identity replaces the previous key.

Key properties

Property	Value
TTL	8 hours (fixed)
Scope	Full workspace API access — same as any virtual key. Combine with team-level budgets and rate limits for guardrails.
Uniqueness	One live SSO key per `(team, email)`. Re-running the flow revokes the previous key.
Audit	Every issuance writes an `sso_issued` event to the key audit log, including the verified email and IdP.
Revocation	Manual via Keys → … → Revoke, or automatic when the sweeper clears the row after `expires_at`.

The 8-hour TTL is a deliberate defense against leaked keys — even if the token ends up in a repo or a chat log, its blast radius closes overnight.

Configuring an IdP connection

Every team that wants SSO device flow needs one idp_config row per login domain. Provision it via the admin API:

curl -X POST https://api.routeshift.io/admin/idp-configs \
  -H "Authorization: Bearer ROUTESHIFT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_…",
    "provider": "okta",
    "login_domain": "acme.com",
    "issuer": "https://acme.okta.com",
    "client_id": "0oab…",
    "client_secret": "…"
  }'

Requirements:

provider — google_workspace or okta.
login_domain — the email domain employees sign in with (e.g. acme.com). A domain belongs to exactly one team; conflicts return 409.
issuer — the OIDC issuer URL. RouteShift fetches its discovery document at create time to validate reachability and the JWKS endpoint. Do not include a trailing slash — the issuer is compared byte-for-byte against the iss claim during token verification.
client_id / client_secret — the OAuth app you registered in the IdP console. The secret is encrypted at rest with PROVIDER_KEY_SECRET.
Redirect URI — register ${SSO_CALLBACK_BASE_URL}/oauth/device/callback in the IdP app console. This must match the environment variable exactly.

The IdP-side redirect URI must exactly match SSO_CALLBACK_BASE_URL configured on the proxy. A mismatch causes the browser leg to fail with an opaque IdP error before RouteShift ever sees the callback.

CLI example

A minimal client that walks the flow:

async function ssoLogin(email: string): Promise<string> {
  // 1. Request a device code
  const start = await fetch("https://proxy.routeshift.io/oauth/device/code", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email }),
  }).then((r) => r.json());

  console.log(`Open ${start.verification_uri_complete}`);
  console.log(`Or visit ${start.verification_uri} and enter code: ${start.user_code}`);

  // 2. Poll for the key
  while (true) {
    await new Promise((r) => setTimeout(r, start.interval * 1000));
    const res = await fetch("https://proxy.routeshift.io/oauth/device/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        device_code: start.device_code,
        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
      }),
    });
    const body = await res.json();
    if (res.ok) return body.access_token; // sk-proxy-…
    if (body.error === "authorization_pending" || body.error === "slow_down") continue;
    throw new Error(body.error_description ?? body.error);
  }
}

The device-code endpoint returns:

{
  "device_code": "…",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://proxy.routeshift.io/oauth/device/verify",
  "verification_uri_complete": "https://proxy.routeshift.io/oauth/device/verify?user_code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}

The token endpoint returns standard RFC 8628 errors:

Error	Meaning
`authorization_pending`	Keep polling — the user hasn’t approved yet.
`slow_down`	You’re polling too fast. Increase the interval by 5 seconds.
`expired_token`	The `device_code` expired (10 minutes). Start over.
`access_denied`	The user clicked Deny on the verify page.
`invalid_grant`	The `device_code` is unknown, already consumed, or malformed.

Rollout gate

The device flow is disabled by default. To enable it on a deployment:

Set SSO_DEVICE_FLOW_ENABLED=true on apps/proxy.
Set SSO_CALLBACK_BASE_URL to the public HTTPS origin of the proxy (must match the redirect URI you register in each IdP).
Provision at least one idp_config via the admin API.

SSO_DEVICE_FLOW_ENABLED is a per-team onboarding gate, not a global kill switch. Once a team has an idp_configs row, flipping the flag off does not stop that team’s employees from logging in. To disable a specific team, delete their idp_configs row via DELETE /admin/idp-configs/{id}?team_id=….

Audit

Every SSO-issued key writes an sso_issued event to api_key_audit_events with the verified email, IdP config ID, and issuance timestamp. Filter for these in the audit log to see which employees are actively using the flow. Revocation, rotation, and expiry follow the same key lifecycle as any other virtual key.

Get started

Features

Integrations

Settings

When to use it

How the flow works

Key properties

Configuring an IdP connection

CLI example

Rollout gate

Audit

​When to use it

​How the flow works

​Key properties

​Configuring an IdP connection

​CLI example

​Rollout gate

​Audit

When to use it

How the flow works

Key properties

Configuring an IdP connection

CLI example

Rollout gate

Audit