Authentication

Sign in to Nexus Suite to unlock Pro and Studio features. Core features work without signing in — no account required.

Overview

Nexus Suite uses JWT-based authentication with RS256 signing. Tokens are issued by the API at api.nexus-suite.dev and validated by all clients using the public key from the JWKS endpoint.

Token	Lifetime	Purpose
Access token (JWT)	15 minutes	Authenticates API requests
Refresh token	30 days	Obtains new access tokens without re-authentication

Refresh tokens are rotated on every use — the old token is immediately invalidated.

Sign In from NexusIDE

NexusIDE uses the Device Code Flow so you authenticate in your browser:

1. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run NexusCore: Sign In
3. NexusIDE displays a verification URL and a device code
4. A browser window opens to nexus-suite.dev/device
5. Enter the device code and sign in with your email, Google, or GitHub account
6. Return to NexusIDE — you're authenticated

NexusIDE stores your refresh token securely in the operating system's credential storage:

Platform	Storage
macOS	Keychain
Windows	Credential Manager
Linux	Secret Service (GNOME Keyring / KWallet)

TIP

The device code expires after 15 minutes. If it expires, NexusIDE will offer to restart the sign-in flow.

Sign-In Dialog

The NexusIDE sign-in dialog presents two options:

• Sign in with Browser — Initiates the Device Code Flow
• Create Account — Opens nexus-suite.dev/register in your browser

Status Bar

After signing in, the status bar shows your subscription tier:

• NexusCore · Pro — Signed in with Pro tier
• NexusCore · Studio — Signed in with Studio tier

When not signed in, the status bar shows NexusCore · Free and all Core features remain available.

Sign In from NexusCore CLI

nexus-cli auth login

The CLI initiates the Device Code Flow and displays instructions:

Sign in to Nexus Suite

  Open this URL in your browser:
  https://nexus-suite.dev/device

  Enter this code: ABCD-1234

  Waiting for authorization...

Once you complete sign-in in the browser, the CLI stores the refresh token at ~/.nexuscore/credentials with file permissions restricted to your user (mode 0600).

Check Auth Status

nexus-cli auth status

Signed in as user@example.com
Tier: Pro
Manage your account at https://nexus-suite.dev/account

Sign Out

nexus-cli auth logout

This deletes the local credentials and notifies the API to revoke the session.

Create an Account

Visit nexus-suite.dev/register to create a Nexus Suite account.

• Email + password — Password must be at least 12 characters
• Google OAuth — Sign up with your Google account
• GitHub OAuth — Sign up with your GitHub account

All new accounts start on the Core tier. A verification email is sent to confirm your address (link expires after 24 hours).

INFO

If you sign up with Google or GitHub, your email is automatically verified.

Manage Your Account

Visit nexus-suite.dev/account to:

• Profile — Update your display name and avatar
• Security — Change your password, link OAuth providers (Google, GitHub)
• Sessions — View active sessions with device type, location, and last activity. Revoke individual sessions or all sessions at once.
• Subscription — View your current plan, billing cycle, and next billing date. Upgrade, downgrade, or cancel.
• API Keys — Manage cloud model provider API keys (Pro/Studio)

Session Management

You can view and revoke active sessions from the Portal:

1. Go to nexus-suite.dev/account
2. Open the Sessions tab
3. Each session shows the device type (IDE, CLI, browser, Telegram), approximate location, and last activity
4. Click Revoke to invalidate a specific session, or Revoke All to sign out everywhere except your current session

When a session is revoked, the associated refresh token and JWT are immediately invalidated. The client will prompt you to sign in again.

Account Lockout

For security, accounts are temporarily locked after 5 failed login attempts within 15 minutes. The lockout lasts 30 minutes, and a notification email is sent to the account owner.

SSO (Studio Tier)

Studio tier organizations can configure SAML 2.0 SSO:

1. Go to the organization admin dashboard on the Portal
2. Open SSO Configuration
3. Upload your identity provider's SAML metadata
4. Team members can then sign in via SSO

All SSO authentication events are logged in the audit log.

Security Details

• JWT signing: RS256 (asymmetric). Public key available at the JWKS endpoint.
• Password hashing: Argon2id with 64 MB memory cost, 3 iterations, 16-byte random salt.
• Refresh token storage: Stored as SHA-256 hashes in the database. The plaintext token is only held by the client.
• Token rotation: Every refresh request issues a new refresh token and invalidates the old one.
• HTTPS only: All API communication is over TLS.

Troubleshooting

"Device code expired"

The device code is valid for 15 minutes. If it expires, restart the sign-in flow from the IDE or CLI.

"Account requires email verification"

Check your inbox for the verification email. If you didn't receive it, visit nexus-suite.dev/register and request a new verification email.

"Account temporarily locked"

Wait 30 minutes or check your email for the lockout notification. If you didn't trigger the lockout, change your password immediately after the lockout expires.

Signed in but features not updating

Entitlement data is cached for 5 minutes. Wait a few minutes after upgrading your subscription, or restart the IDE/CLI to force a refresh.