Skip to content

Cortex AI Authentication Guide

🔐 Authentication Methods

Cortex AI supports two authentication methods:

  1. Portal Tokens (Recommended) ⭐⭐⭐⭐⭐
  2. Zitadel SSO (Legacy)

Why Portal Tokens?

  • ✅ Usage Tracking - Every API call is tracked per user
  • ✅ Token Management - Create, revoke, and manage tokens
  • ✅ Long-lived - Tokens last 1 year
  • ✅ Offline-friendly - No browser popups
  • ✅ Industry Standard - Like GitHub Copilot, Cursor, Augment

How to Get a Portal Token

Step 1: Sign Up / Login

  1. Go to https://app.cortex.emshvac.co
  2. Click "Login with Zitadel"
  3. Authenticate with your Zitadel account
  4. You'll be redirected to the Cortex Portal dashboard

Step 2: Generate a Token

  1. On the dashboard, find the "Personal Access Tokens" section
  2. Click "+ Create Token"
  3. A new token will be generated (format: portal_xxx...)
  4. Copy the token immediately - it won't be shown again!

Step 3: Configure VSCode

Option A: Via Settings UI 1. Open VSCode Settings (Cmd+, or Ctrl+,) 2. Search for "Cortex AI Token" 3. Paste your token in the cortexAI.token field

Option B: Via Command Palette 1. Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P) 2. Type "Cortex: Configure Token" 3. Paste your token when prompted

Option C: Via settings.json 

{
  "cortexAI.token": "portal_xxx..."
}

Step 4: Start Using Cortex!

That's it! The extension will now use your portal token for all API requests.

📊 Usage Tracking

What Gets Tracked?

When you use a portal token, the following is tracked in the database:

  • Owner - Your email address
  • Last Used - Timestamp of last API call
  • Roles - Your permission level (admin, user, etc.)
  • Permissions - Fine-grained access control

View Your Usage

  1. Go to https://app.cortex.emshvac.co
  2. View your tokens and their last usage
  3. See which tokens are active

Benefits

  • Accountability - Know who's using the API
  • Analytics - Track usage patterns
  • Cost Attribution - Allocate costs per user
  • Security - Revoke compromised tokens instantly

🔄 Token Management

Create Multiple Tokens

You can create multiple tokens for different purposes: - One for your work laptop - One for your personal laptop - One for CI/CD pipelines

Revoke Tokens

If a token is compromised: 1. Go to https://app.cortex.emshvac.co 2. Find the token in your dashboard 3. Click "Revoke" 4. The token is immediately invalidated

Token Expiration

  • Tokens expire after 1 year
  • You'll receive a notification before expiration
  • Generate a new token when needed

🔐 LEGACY: Zitadel SSO (Device Code Flow)

When to Use

Only use this if: - You can't access the portal - You need temporary access - You're testing authentication

How It Works

  1. VSCode prompts for login
  2. Opens browser to Zitadel
  3. You enter a device code
  4. VSCode receives a JWT token
  5. Token is stored in VSCode secrets

Limitations

  • ❌ No usage tracking - JWT tokens don't hit the database
  • ❌ Short-lived - Tokens expire quickly
  • ❌ Browser required - Can't work offline
  • ❌ Complex UX - Device code flow is confusing

How to Use

  1. Make sure cortexAI.token is empty
  2. Make sure cortexAI.enableAuth is true
  3. Try to use Cortex
  4. VSCode will prompt for Zitadel login
  5. Follow the device code flow

For Individual Users

  1. ✅ Use Portal Tokens
  2. ✅ Generate one token per device
  3. ✅ Revoke tokens when changing devices
  4. ✅ Check usage periodically

For Teams

  1. ✅ Each user gets their own Zitadel account
  2. ✅ Each user generates their own portal token
  3. ✅ Admins can track usage per user
  4. ✅ Revoke access by revoking tokens

For CI/CD

  1. ✅ Create a service account in Zitadel
  2. ✅ Generate a portal token for the service account
  3. ✅ Store token in CI/CD secrets
  4. ✅ Track CI/CD usage separately

🔍 Troubleshooting

"Invalid or expired token"

  1. Check if token starts with portal_
  2. Check if token is revoked in the portal
  3. Check if token has expired (1 year)
  4. Generate a new token

"No token configured"

  1. Open VSCode settings
  2. Search for "Cortex AI Token"
  3. Paste your portal token
  4. Reload VSCode

"Failed to authenticate"

  1. Check if cortex.emshvac.co is accessible
  2. Check your internet connection
  3. Try generating a new token
  4. Contact support

📝 Summary

Feature Portal Token Zitadel SSO
Usage Tracking ✅ Yes ❌ No
Token Management ✅ Yes ❌ No
Long-lived ✅ 1 year ❌ Short
Offline ✅ Yes ❌ No
UX ✅ Simple ❌ Complex
Recommended ✅ YES ❌ Legacy

Get started now: https://app.cortex.emshvac.co 🚀