Skip to Content
Alprina is in active development. Join us in building the future of security scanning.
GuidesAuthentication Guide

Authentication Guide

Alprina offers three authentication methods to suit different use cases. Choose the method that best fits your workflow.

Authentication Methods

1. GitHub OAuth (Web Dashboard)

Best for: Users who prefer browser-based access

How it works:

  1. Visit alprina.com 
  2. Click “Sign in with GitHub”
  3. Authorize Alprina to access your GitHub account
  4. Redirected to dashboard
  5. API key automatically generated

Advantages:

  • ✅ Quick and easy
  • ✅ No password to remember
  • ✅ Leverages GitHub security (2FA, etc.)
  • ✅ Automatic API key generation

Use cases:

  • First-time users
  • Dashboard access
  • Quick project setup

2. API Key Authentication (CLI & API)

Best for: Command-line users, CI/CD pipelines, programmatic access

How it works:

  1. Generate API key from dashboard
  2. Set environment variable or use CLI login
  3. Run commands authenticated

Setup:

# Method A: Environment variable (recommended)
export ALPRINA_API_KEY="sk_live_your_key_here"
alprina scan ./src
 
# Method B: CLI login
alprina auth login --api-key sk_live_your_key_here
alprina scan ./src
 
# Method C: Per-command
alprina scan ./src --api-key sk_live_your_key_here

Advantages:

  • ✅ Works in headless environments
  • ✅ Perfect for automation
  • ✅ Fine-grained access control (coming: scoped keys)
  • ✅ Easy to rotate

Use cases:

  • CI/CD pipelines
  • Automated scripts
  • Server deployments
  • API integrations

3. Device Authorization Flow (CLI Interactive)

Best for: CLI users who prefer browser login

How it works:

  1. Run alprina auth login (no flags)
  2. CLI displays a code and URL
  3. Open URL in browser
  4. Enter code
  5. Authorize in browser
  6. CLI automatically authenticated

Example:

$ alprina auth login
 
Opening browser for authentication...
 
Visit: https://www.alprina.com/authorize
Enter code: ABCD-1234
 
Waiting for authorization...
✓ Authentication successful!
API key saved to ~/.alprina/config.json

Advantages:

  • ✅ No need to copy/paste API keys
  • ✅ Browser-based security
  • ✅ Easy for first-time CLI users
  • ✅ Automatic key storage

Use cases:

  • Local development
  • First-time CLI setup
  • Users uncomfortable with API keys

Quick Start by Use Case

For Dashboard Users

1. Go to alprina.com
2. Click "Sign in with GitHub"
3. Authorize
4. Start using dashboard

For CLI Users (First Time)

# Interactive browser flow
alprina auth login
 
# Or with API key from dashboard
alprina auth login --api-key sk_live_...

For CI/CD Pipelines

# GitHub Actions example
- name: Alprina Scan
  run: alprina scan ./src
  env:
    ALPRINA_API_KEY: ${{ secrets.ALPRINA_API_KEY }}

For API Integration

import alprina
 
client = alprina.Client(
    api_key=os.getenv("ALPRINA_API_KEY")
)
 
result = client.scan("./src", scan_type="code")

Authentication Flow Diagrams

GitHub OAuth Flow

User → GitHub → Supabase Auth → Alprina Backend → Dashboard
                    ↓
              JWT Token Created
                    ↓
              API Key Generated

API Key Flow

Dashboard → Create API Key → Copy Key → Set in Environment
                                ↓
                          Use in CLI/API

Device Authorization Flow

CLI → Request Code → Display to User
       ↓
Browser → Enter Code → Authorize
       ↓
CLI ← Receive Token ← Backend validates
       ↓
   Save to config

Managing Authentication

Check Current Auth Status

# CLI
alprina auth status
 
# Output:
# ✓ Authenticated
# User: john@example.com
# Tier: Developer
# API Key: sk_live_...abc (last 3 chars)
# Expires: Never

Logout

# Remove stored credentials
alprina auth logout
 
# Confirm:
# ✓ Logged out successfully
# Local credentials removed

Switch Accounts

# Logout first
alprina auth logout
 
# Login with different account
alprina auth login --api-key sk_live_different_key

Security Best Practices

For API Keys

  1. Never commit to Git

    # .gitignore
.env
.alprina/
alprina-config.json

  2. Use environment variables

    # .env
ALPRINA_API_KEY=sk_live_...
 
# Load in scripts
source .env
alprina scan ./src

  3. Rotate regularly

    # Every 90 days
# 1. Create new key in dashboard
# 2. Update systems
# 3. Revoke old key

  4. Use separate keys per environment

    Production: sk_live_prod_...
Staging: sk_live_staging_...
CI/CD: sk_live_ci_...
Development: sk_live_dev_...

For GitHub OAuth

  1. Enable 2FA on GitHub
  2. Review authorized apps regularly
  3. Revoke access if account compromised

For All Methods

  1. Monitor login activity (coming soon)
  2. Set up alerts for unusual activity (coming soon)
  3. Use strong passwords for dashboard
  4. Keep CLI updated: pip install --upgrade alprina-cli

Troubleshooting

Authentication Failed

Symptoms:

Error: 401 Unauthorized
Invalid API key

Solutions:

  1. Check API key is correct
  2. Verify not revoked in dashboard
  3. Try generating new key
  4. Ensure no extra spaces/newlines

GitHub OAuth Not Working

Symptoms:

  • Redirect fails
  • Authorization doesn’t complete

Solutions:

  1. Check browser cookies enabled
  2. Disable ad blockers
  3. Try incognito/private mode
  4. Clear browser cache
  5. Try different browser

Device Flow Timeout

Symptoms:

Error: Authorization timeout
Device code expired

Solutions:

  1. Restart: alprina auth login
  2. Complete authorization within 15 minutes
  3. Check internet connection
  4. Try API key method instead

Permission Denied

Symptoms:

Error: 403 Forbidden
Insufficient permissions

Solutions:

  1. Check subscription tier
  2. Verify API key scopes (when available)
  3. Contact support

Migration Guide

From Trial to Paid

  1. Upgrade in dashboard: Settings → Billing → Upgrade
  2. Authentication remains the same
  3. API keys continue working
  4. No re-authentication needed

From Old API Keys

If you have old API keys:

  1. Generate new keys in dashboard
  2. Update systems with new keys
  3. Revoke old keys
  4. Old format: api_... (deprecated)
  5. New format: sk_live_... (current)

API Reference

For complete API documentation:

FAQ

Q: Which authentication method should I use? A: Dashboard users: GitHub OAuth. CLI/API users: API keys. First-time CLI: Device flow.

Q: Can I use multiple authentication methods? A: Yes, use GitHub OAuth for dashboard and API keys for CLI/API.

Q: How long do sessions last? A: Dashboard sessions: 7 days. API keys: No expiration (manual rotation recommended).

Q: Can I share API keys with my team? A: No, each team member should have their own account and API keys. Use Team tier for collaboration.

Q: What happens if my API key is compromised? A: Immediately revoke in dashboard, generate new key, update systems.

Q: Do I need to re-authenticate after upgrading? A: No, authentication persists across tier changes.

Last updated on
API Key ManagementGDPR Compliance