Authentication

Quick Start

Get scan results in the cloud dashboard in under 60 seconds:

skylos . --upload

First run:

1. Browser opens automatically
2. Sign in with GitHub, pick (or create) a project
3. Results upload to dashboard
4. Future uploads work automatically

No API keys to copy, no config files, no manual setup.

---

Browser Authentication

What Changed in v3.3.0?

Skylos now offers seamless browser-based authentication similar to tools like GitHub CLI and Vercel.

Before (manual token): Visit dashboard → Create project → Copy token → Set env var → Upload (~5 minutes, 6+ steps)

After (browser auth): Run skylos . --upload (~30 seconds, 1 command)

How It Works

1. CLI opens your browser to Skylos Cloud
2. You log in with GitHub (if not already logged in)
3. You select an existing project or create a new one
4. CLI automatically receives the token and saves it
5. You're ready to upload — no copy/pasting required

Terminal Output

$ skylos . --upload

Scanning Python files...
✓ Found 15 issues

No Skylos token found. Let's connect to Skylos Cloud.

Opening browser to connect to Skylos Cloud...
If the browser doesn't open, visit:
  https://skylos.dev/cli/connect?port=54321&repo=myproject

Waiting for authentication (press Ctrl+C to cancel)...

✓ Connected to Skylos Cloud!
  Project:      my-project
  Organization: My Team
  Plan:         Pro

Uploading scan results...
✓ Upload complete! View at https://skylos.dev/dashboard

Explicit Login Command

For more control, use the dedicated login command:

skylos login

Use cases:

• Switch to a different project
• Set up before running scans
• Prefer explicit authentication steps

---

Manual Tokens

The manual token method is still fully supported for backward compatibility and headless environments.

Steps

1. Visit skylos.dev/dashboard
2. Create a project manually
3. Go to Settings → API Keys
4. Copy the API token
5. Set environment variable:

   export SKYLOS_TOKEN=sky_live_xxx...

6. Run scan with upload:

   skylos . --upload

When to Use Manual Tokens

• CI/CD pipelines where you want explicit token management
• Automation scripts that need predictable behavior
• Shared environments where browser auth isn't practical
• Air-gapped systems without internet access to Skylos Cloud

---

GitHub Actions OIDC (Tokenless)

Recommended for GitHub Actions

OIDC authentication requires zero secrets — the most secure CI approach.

GitHub Actions can authenticate with Skylos Cloud using OpenID Connect. No SKYLOS_TOKEN secret needed.

Setup

name: Skylos Scan
on: [pull_request]

permissions:
  contents: read
  id-token: write  # Enables tokenless auth

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install skylos
      - run: skylos . --danger --upload  # No token needed!

How It Works

1. GitHub Actions generates a short-lived OIDC token
2. Token contains claims: repository, actor, ref, sha
3. Skylos verifies the token against GitHub's public JWKS endpoint
4. Skylos matches the repository to your project in the database
5. Upload proceeds without any secrets

Benefits

• Zero secrets to manage, rotate, or leak
• Short-lived tokens that expire in minutes
• Cryptographically signed by GitHub
• Repository-bound — can't be stolen or reused elsewhere

---

Other CI Systems

For GitLab CI, CircleCI, Jenkins, and other CI systems, use the SKYLOS_TOKEN environment variable:

1. Get your token: skylos.dev/dashboard/settings
2. Add as a secret in your CI provider
3. Reference it as SKYLOS_TOKEN

GitLab CI:

skylos:
  script:
    - pip install skylos
    - skylos . --danger --upload
  variables:
    SKYLOS_TOKEN: $SKYLOS_TOKEN

CircleCI:

- run:
    name: Skylos Scan
    command: skylos . --danger --upload
    environment:
      SKYLOS_TOKEN: $SKYLOS_TOKEN

See CI/CD Integration for complete CI setup guides.

---

Token Priority

The CLI checks for tokens in this order (highest priority first):

1. SKYLOS_TOKEN environment variable
2. GitHub Actions OIDC (only in GitHub Actions with id-token: write)
3. Linked project token (from .skylos/link.json + ~/.skylos/credentials.json)
4. Legacy global token (deprecated: top-level token field in credentials)
5. System keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)

You can override the linked project for one-off scans:

SKYLOS_TOKEN=sky_live_xxx skylos . --upload

---

Multi-Project Management

Browser auth manages tokens per repository automatically:

# Project A - authenticate once
cd ~/projectA
skylos login  # Pick "Project A" in browser
skylos . --upload

# Project B - authenticate once
cd ~/projectB
skylos login  # Pick "Project B" in browser
skylos . --upload

# Future uploads remember the project!
cd ~/projectA && skylos . --upload  # Uses Project A token
cd ~/projectB && skylos . --upload  # Uses Project B token

The CLI remembers which project each repository is linked to via .skylos/link.json.

Switching Projects

skylos login  # Browser opens → pick a different project

Or use an explicit token:

SKYLOS_TOKEN=sky_live_xxx skylos . --upload

---

Headless Environments

SSH / Remote Servers

When running over SSH without display access, the CLI automatically falls back to manual token entry:

$ skylos login

Browser auth unavailable: No display available

Manual connection
Get your API key at: https://skylos.dev/dashboard/settings

Paste your API token: [paste here]

✓ Connected to Skylos Cloud!
  Project:      My Project
  Organization: My Team

Docker / CI

The CLI detects CI environments and provides appropriate instructions. For GitHub Actions, it suggests OIDC if id-token: write permission isn't set.

---

Migration Guide

Local Development: Old → New

Remove your old token and let browser auth take over:

# Remove environment variable
unset SKYLOS_TOKEN

# Remove from shell profile (~/.bashrc, ~/.zshrc)
# Delete the SKYLOS_TOKEN line

# Run upload - browser auth kicks in automatically
skylos . --upload

Environment variables always take priority, so remove SKYLOS_TOKEN from your shell profile to use browser auth.

GitHub Actions: Manual Token → OIDC

Before:

- name: Scan and Upload
  env:
    SKYLOS_TOKEN: ${{ secrets.SKYLOS_TOKEN }}
  run: skylos . --danger --upload

After:

# Add at top of workflow
permissions:
  contents: read
  id-token: write

# Update step (remove SKYLOS_TOKEN)
- name: Scan and Upload
  run: skylos . --danger --upload

Steps:

1. Add id-token: write permission to workflow
2. Remove SKYLOS_TOKEN from workflow env
3. Push the change — done!
4. (Optional) Keep the secret around for rollback

Other CI Systems

No migration needed. Continue using SKYLOS_TOKEN as before. Browser auth only affects local CLI usage.

---

Security Notes

Browser Auth vs Manual Tokens

Aspect	Manual Tokens	Browser Auth
Storage	Environment variable (visible in env, process list)	File with 600 permissions (owner-only)
Visibility	Visible in shell history if set inline	Never visible in shell history
Rotation	Manual (must update everywhere)	Automatic (re-run skylos login)
Multi-project	One token = one project	Manages all projects automatically

Recommendation: Browser auth is more secure for local development.

Token Scopes

Skylos API tokens are project-scoped:

• Each token grants access to one project only
• Tokens cannot access other projects in your organization
• Tokens can be revoked individually from the dashboard

OIDC Security (GitHub Actions)

Aspect	Manual Tokens	OIDC Tokens
Lifetime	Until revoked	Minutes
Secrets to manage	1+	0
Can be stolen/reused	⚠️ If leaked	❌ Bound to repo
Rotation	Manual	Automatic

File Permissions

• Tokens are stored with 600 permissions (owner read/write only)
• On macOS/Windows, tokens can optionally use system keyring
• Never commit ~/.skylos/credentials.json or .skylos/link.json to version control

---

Troubleshooting

Browser doesn't open

The CLI prints a URL you can open manually:

Opening browser to connect to Skylos Cloud...
If the browser doesn't open, visit:
  https://skylos.dev/cli/connect?port=54321&repo=myproject

"Already connected" message

You're good — just run skylos . --upload. To reconnect to a different project, type y when prompted or delete .skylos/link.json.

"Invalid token" error (401)

Token may have expired or been revoked:

rm ~/.skylos/credentials.json .skylos/link.json
skylos login  # Re-authenticate

CI upload fails with "No token found"

For GitHub Actions:

• Ensure workflow has id-token: write permission
• Use Skylos CLI v3.3.0 or later
• Verify project has the correct repo URL in dashboard

For other CI:

• Verify SKYLOS_TOKEN secret is set correctly
• Check the secret name matches exactly

SSH/Headless: "Browser auth unavailable"

This is expected. The CLI automatically falls back to manual token entry. Follow the printed instructions.

Disconnecting

rm .skylos/link.json              # Disconnect this project
rm ~/.skylos/credentials.json     # Remove all credentials

Or:

skylos sync disconnect

---

FAQ

Can I use both browser auth and manual tokens?

Yes! Environment variables (SKYLOS_TOKEN) always take priority. Browser auth is used when no token is found in the environment.

Do I need to re-authenticate often?

No. Tokens are saved permanently until you disconnect or they're revoked. You authenticate once per project.

Does this work offline?

No, browser auth requires internet. For offline scans (without --upload), no authentication is needed.

What about team sharing?

Each developer authenticates individually. The .skylos/link.json file can optionally be committed to share the project ID, but tokens are always user-specific and stored in ~/.skylos/credentials.json.

Can I keep using the old method?

Absolutely. The manual token method is fully supported. Set SKYLOS_TOKEN and it takes priority over browser auth.

How do I manage 10+ projects?

Browser auth handles this automatically. Each repo gets linked to its project. No more managing multiple environment variables.