API Key Management

Learn how to create, manage, and secure your Alprina API keys for CLI and programmatic access.

Overview

API keys allow you to authenticate with the Alprina API and CLI without using your password. Each key can be:

• Named for easy identification
• Individually revoked
• Tracked with last-used timestamps
• Scoped to specific permissions (coming soon)

Creating API Keys

From Dashboard

1. Login to Dashboard

   • Visit alprina.com/dashboard 
   • Sign in with GitHub or email

2. Navigate to API Keys

   • Click on your profile in the top right
   • Select “API Keys” from the dropdown
   • Or go directly to Settings → API Keys

3. Generate New Key

   • Click “Generate New API Key”
   • Enter a descriptive name (e.g., “Production Server”, “CI/CD Pipeline”)
   • Click “Create”

4. Copy and Store Key

   • ⚠️ Important: Copy the key immediately
   • The full key is only shown once
   • Store it securely (password manager, secrets vault)

Example:

Key Name: Production Server
API Key: sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
Created: January 5, 2025
Last Used: Never

From CLI

You can also generate keys using the CLI:

# Login first (uses GitHub OAuth)
alprina auth login
 
# Generate new API key
alprina auth api-key create --name "My CLI Key"
 
# Output:
# ✓ API key created successfully
# Name: My CLI Key
# Key: sk_live_...
# ⚠️  Save this key securely. It won't be shown again.

Using API Keys

CLI Authentication

Method 1: Environment Variable (Recommended)

# Set environment variable
export ALPRINA_API_KEY="sk_live_your_key_here"
 
# Use CLI normally
alprina scan ./src
alprina chat

Add to your shell profile for persistence:

# ~/.bashrc or ~/.zshrc
export ALPRINA_API_KEY="sk_live_your_key_here"

Method 2: CLI Login

# Login with API key
alprina auth login --api-key sk_live_your_key_here
 
# Key is stored in ~/.alprina/config.json
# Future commands use this key automatically
alprina scan ./src

Method 3: Per-Command

# Use key for single command
alprina scan ./src --api-key sk_live_your_key_here

API Requests

Include your API key in the Authorization header:

curl -X POST https://api.alprina.com/v1/scan/code \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "./src",
    "language": "python"
  }'

Python SDK

import alprina
 
# Set API key
client = alprina.Client(api_key="sk_live_your_key_here")
 
# Or use environment variable
import os
client = alprina.Client(api_key=os.getenv("ALPRINA_API_KEY"))
 
# Run scan
result = client.scan("./src", scan_type="code")

JavaScript/Node.js

import Alprina from 'alprina-sdk';
 
// Initialize client
const alprina = new Alprina({
  apiKey: process.env.ALPRINA_API_KEY
});
 
// Run scan
const result = await alprina.scan({
  target: './src',
  scanType: 'code'
});

Managing API Keys

Viewing Keys

Dashboard:

• Navigate to Settings → API Keys
• View all keys with:
  • Name
  • Prefix (first 8 characters)
  • Created date
  • Last used timestamp
  • Status (active/revoked)

CLI:

# List all API keys
alprina auth api-key list
 
# Output:
# ID          Name              Created         Last Used
# key_abc123  Production Server Jan 1, 2025    2 hours ago
# key_def456  CI/CD Pipeline    Jan 3, 2025    5 minutes ago
# key_ghi789  Development       Jan 5, 2025    Never

Renaming Keys

# Rename via CLI
alprina auth api-key rename key_abc123 --name "New Production Key"
 
# Or via dashboard
# Settings → API Keys → Click key → Edit name

Revoking Keys

When to Revoke:

• Key accidentally exposed
• No longer needed
• Rotating keys for security
• Team member leaves

Dashboard:

1. Go to Settings → API Keys
2. Find the key to revoke
3. Click “Revoke” button
4. Confirm revocation

CLI:

# Revoke specific key
alprina auth api-key revoke key_abc123
 
# Confirm:
# ⚠️  Are you sure you want to revoke "Production Server"?
# This action cannot be undone. (y/N): y
# ✓ API key revoked successfully

API:

curl -X DELETE https://api.alprina.com/v1/auth/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rotating Keys

Best practice: Rotate keys every 90 days

# Step 1: Create new key
alprina auth api-key create --name "Production Server v2"
 
# Step 2: Update systems with new key
# (update environment variables, secrets managers, etc.)
 
# Step 3: Verify new key works
ALPRINA_API_KEY=new_key alprina scan ./test
 
# Step 4: Revoke old key
alprina auth api-key revoke key_old123

Security Best Practices

DO ✅

1. Use Environment Variables

   # Good
   export ALPRINA_API_KEY="sk_live_..."
   alprina scan ./src

2. Store in Secrets Manager

   • AWS Secrets Manager
   • HashiCorp Vault
   • GitHub Secrets
   • Azure Key Vault

3. Use Descriptive Names

   Good: "Production API Server", "GitHub Actions CI"
   Bad: "Key 1", "test", "my key"

4. Rotate Regularly

   • Every 90 days minimum
   • After team member departure
   • If exposure suspected

5. Use Separate Keys per Environment

   production-key: For production systems
   staging-key: For staging environment
   ci-key: For CI/CD pipelines
   dev-key: For local development

6. Monitor Usage

   • Check “Last Used” timestamps
   • Revoke unused keys
   • Review API key list monthly

DON’T ❌

1. Hardcode in Source Code

   # BAD - Never do this!
   api_key = "sk_live_abc123..."
   client = Alprina(api_key=api_key)

2. Commit to Version Control

   # Add to .gitignore
   echo ".env" >> .gitignore
   echo "*.key" >> .gitignore
   echo "alprina-config.json" >> .gitignore

3. Share via Email/Slack

   • Use secure sharing tools
   • Or regenerate key for recipient

4. Use Same Key Everywhere

   • Create separate keys per use case
   • Easier to track and revoke

5. Ignore Security Warnings

   # If you see this, take action!
   ⚠️  Warning: API key exposed in git history

CI/CD Integration

GitHub Actions

# .github/workflows/security-scan.yml
name: Security Scan
 
on: [push, pull_request]
 
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Run Alprina Scan
        run: alprina scan ./src --fail-on high
        env:
          ALPRINA_API_KEY: ${{ secrets.ALPRINA_API_KEY }}

Setup:

1. Generate API key: “GitHub Actions CI”
2. Add to repository secrets: Settings → Secrets → New secret
3. Name: ALPRINA_API_KEY
4. Value: Your API key

GitLab CI

# .gitlab-ci.yml
security_scan:
  script:
    - pip install alprina-cli
    - alprina scan ./src
  variables:
    ALPRINA_API_KEY: $ALPRINA_API_KEY

Setup:

1. Generate API key: “GitLab CI”
2. Add to CI/CD variables: Settings → CI/CD → Variables
3. Key: ALPRINA_API_KEY
4. Value: Your API key
5. Check “Mask variable” and “Protect variable”

Jenkins

pipeline {
  agent any
 
  environment {
    ALPRINA_API_KEY = credentials('alprina-api-key')
  }
 
  stages {
    stage('Security Scan') {
      steps {
        sh 'alprina scan ./src'
      }
    }
  }
}

Setup:

1. Generate API key: “Jenkins Pipeline”
2. Add credentials: Jenkins → Credentials → Add
3. Kind: Secret text
4. Secret: Your API key
5. ID: alprina-api-key

Troubleshooting

Invalid API Key

Error:

Error: Invalid API key
Status: 401 Unauthorized

Solutions:

1. Verify key is correct (no extra spaces)
2. Check key hasn’t been revoked
3. Ensure using latest key if rotated
4. Generate new key if lost

API Key Not Found

Error:

Error: ALPRINA_API_KEY environment variable not set

Solutions:

# Check if set
echo $ALPRINA_API_KEY
 
# Set it
export ALPRINA_API_KEY="sk_live_..."
 
# Or login
alprina auth login --api-key sk_live_...

Permission Denied

Error:

Error: 403 Forbidden
Insufficient permissions for this operation

Solutions:

1. Check your subscription tier
2. Verify API key has required scopes
3. Contact support if issue persists

Rate Limit Exceeded

Error:

Error: 429 Too Many Requests
Rate limit: 60 requests/minute exceeded

Solutions:

1. Wait 1 minute before retrying
2. Implement exponential backoff
3. Upgrade tier for higher limits
4. Use separate keys for different services

API Key Formats

Key Structure

sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
│  │    └────────────────────────────────────────────────────┘
│  │                          │
│  │                    Random string (48 chars)
│  │
│  └─ Environment (live/test)
│
└─ Prefix (secret key)

• Prefix: sk_ (secret key)
• Environment: live_ or test_
• Random: 48 character random string
• Total length: 56 characters

Test vs Live Keys

Test Keys (sk_test_...):

• For development and testing
• Limited features
• Separate quota
• Free tier only

Live Keys (sk_live_...):

• For production use
• Full features
• Production quota
• All tiers

Scoped API Keys (Coming Soon)

Future enhancement: Create keys with limited scopes

# Read-only key (planned)
alprina auth api-key create \
  --name "Monitoring Service" \
  --scopes "scans:read"
 
# Scan-only key (planned)
alprina auth api-key create \
  --name "CI/CD Scanner" \
  --scopes "scans:write,scans:read"

FAQ

Q: How many API keys can I create? A: No limit. Create as many as needed for different services.

Q: Do API keys expire? A: No, but we recommend rotating every 90 days.

Q: Can I recover a revoked key? A: No, revocation is permanent. Generate a new key.

Q: What if I lose my API key? A: Revoke the lost key and generate a new one.

Q: Can I see my full API key after creation? A: No, it’s only shown once for security. Save it immediately.

Q: How do I know which key to revoke? A: Use descriptive names and check “Last Used” timestamps.

Related

• Authentication Guide
• CLI Reference
• API Reference
• CI/CD Integration