Device code authentication

The device code flow lets you authenticate the CLI (or any headless client) by logging in through your browser. This follows the same pattern as gh auth login or az login.

How it works

1. The CLI requests a device code.
2. You open a URL in your browser and enter a short code.
3. The CLI polls until you approve, then receives a token.

Step 1: Request a device code

The CLI calls:

curl -X POST https://api.fold.run/auth/device/code

Response:

{
  "device_code": "dc_a1b2c3d4...",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://app.fold.run/console/device",
  "expires_in": 600,
  "interval": 5
}

Field	Description
device_code	Secret code the CLI uses to poll for the token
user_code	Short code you enter in the browser (8 characters)
verification_uri	URL to open in your browser
expires_in	Seconds until the code expires (10 minutes)
interval	Recommended polling interval in seconds

Step 2: Approve in the browser

Open the verification_uri in your browser. Log in if needed, then enter the user_code displayed by the CLI.

The user code uses only unambiguous characters (no I, O, 0, or 1) to avoid confusion.

Step 3: Poll for the token

The CLI polls until approval:

curl -X POST https://api.fold.run/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "dc_a1b2c3d4..." }'

While waiting, the response is:

{
  "error": "authorization_pending"
}

After you approve in the browser:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "usr_abc123",
    "email": "you@example.com",
    "role": "admin"
  }
}

The token is long-lived (30 days) for CLI use.

Using the CLI

The fold login command handles this flow automatically:

fold login
# → Opening browser... Enter code: ABCD-EFGH
# → Waiting for approval...
# → Logged in as you@example.com

See CLI for the full command reference.

Security

• Device codes expire after 10 minutes.
• Each device code can only be used once.
• The approval endpoint requires an authenticated browser session.
• Rate limits apply to the code request endpoint.