Jamdesk Documentation logo

Authentication

Log in, check sessions, and see how the Jamdesk CLI authenticates. Covers token storage, session refresh, team accounts, and CI/CD environments.

The CLI logs in to your Jamdesk account through the browser. Log in before you deploy.

Login

jamdesk login

This opens the Jamdesk dashboard in your browser. The flow:

  1. The CLI starts a local HTTP server on 127.0.0.1:9876 (falls back to an OS-assigned port if 9876 is busy)
  2. Your browser opens to dashboard.jamdesk.com/cli-auth
  3. You authenticate using any dashboard login method (email/password, Google, GitHub)
  4. The dashboard sends your credentials back to the CLI's local server
  5. Credentials are stored in ~/.jamdeskrc

The CLI verifies a state parameter on callback to prevent cross-site request forgery. The login flow times out after 2 minutes.

Expected output
$ jamdesk login
ℹ Open this URL in your browser to log in:

  https://dashboard.jamdesk.com/cli-auth?port=9876&state=abc123...

ℹ Waiting for authentication...
✔ Logged in as you@example.com

Headless and SSH environments: The CLI always prints the URL to the terminal, even when it can't open a browser. Paste the URL into any browser.

Logout

jamdesk logout

Clears stored credentials from ~/.jamdeskrc. Does nothing if you're not logged in.

Expected output
$ jamdesk logout
✔ Logged out (you@example.com)

Whoami

jamdesk whoami

Shows your logged-in email. It refreshes the token to validate the session. It never reads a local cache.

Possible states:

$ jamdesk whoami
✔ Logged in as you@example.com

How Sessions Work

Credentials are stored in ~/.jamdeskrc as JSON with 0600 permissions (owner-only read/write):

~/.jamdeskrc
{
  "auth": {
    "refreshToken": "AGK...",
    "email": "you@example.com",
    "uid": "abc123",
    "expiresAt": 1700000000000
  }
}

The CLI uses a refresh token + ID token architecture:

  • ID tokens expire in ~1 hour and are used for API calls
  • The CLI auto-refreshes ID tokens with the stored refresh token 5 minutes before expiry
  • Refresh tokens are long-lived but can be revoked (password change, account deletion)
  • The CLI clears stored auth when the refresh token is permanently invalid (TOKEN_EXPIRED, USER_NOT_FOUND, INVALID_REFRESH_TOKEN)

The CLI refreshes tokens on every authenticated command. You never refresh them by hand.

Troubleshooting

A firewall may block the CLI's local callback server. Copy the printed URL and open it in your browser.

The CLI picks a different port when another process uses 9876. Check the URL in the terminal output.

Your refresh token is no longer valid. This happens after password changes or long periods of inactivity.

Run jamdesk login to get a fresh session.

Headless environments (SSH, Docker, CI) can't open a browser. Copy the URL from the terminal and open it in any browser that can reach your machine's callback port.

Check that ~/.jamdeskrc exists and contains an auth key:

cat ~/.jamdeskrc

File permissions should be 0600. A missing file can mean a permission problem on your home directory. Check it with ls -la ~.

For more CLI troubleshooting, see the Help Center CLI guide.

What's Next?

CLI Deploy

Deploy your docs from the terminal

CLI Overview

All CLI commands at a glance