Skip to main content

Understanding Deployment Access Keys

The deployment access key is the primary authentication mechanism for Alactic AGI. This guide explains what it is, how it works, and how to manage it.

What is a Deployment Access Key?​

The deployment access key is a unique, cryptographically-generated identifier assigned to your Alactic AGI deployment. It serves as the authentication token for all interactions with your instance.

Format: ak- followed by 40 alphanumeric characters
Example: ak-7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e

Key Characteristics:

  • Unique per deployment
  • Generated during Azure resource creation
  • Stored in Azure Key Vault
  • Cannot be changed or regenerated
  • Required for all frontend and API access

How Access Keys Work​

Generation Process​

  1. ARM template deployment begins
  2. Azure generates unique string based on:
    • Resource group ID
    • Deployment name
    • Timestamp
  3. Key is hashed and prefixed with ak-
  4. Stored in Azure Key Vault as DEPLOYMENT-ACCESS-KEY secret
  5. Exposed as deployment output

Authentication Flow​

  1. User enters key in access gate interface
  2. Browser stores key in localStorage
  3. Frontend sends key in HTTP headers with every API request
  4. Backend validates key against Key Vault value
  5. Request is authorized or rejected

Storage Locations​

Your deployment key exists in three places:

Azure Key Vault (Source of Truth)

  • Location: Key Vault resource in your resource group
  • Secret name: DEPLOYMENT-ACCESS-KEY
  • Access: Via Managed Identity or Azure CLI
  • Viewable in Azure Portal under "Secrets"

VM Environment (Runtime)

  • Location: Application .env file on VM
  • Variable: DEPLOYMENT_ACCESS_KEY=ak-xxxxx
  • Used by backend for validation
  • File permissions: 600 (owner read/write only)

Browser localStorage (Client)

  • Key: alactic_deployment_key
  • Value: ak-xxxxx
  • Scope: Per-domain
  • Persists across browser sessions
  • Cleared when logging out

Finding Your Deployment Access Key​

Method 1: Deployment Outputs (Easiest)​

Immediately after deployment:

  1. Go to Azure Portal
  2. Navigate to "Deployments" in your resource group
  3. Click on the Alactic AGI deployment
  4. Click "Outputs" tab
  5. Copy deploymentAccessKey value

Note: Outputs remain available indefinitely, so you can retrieve the key anytime.

  1. Go to Azure Portal
  2. Navigate to your resource group
  3. Open the Key Vault resource (name: <prefix>-kv-<suffix>)
  4. Click "Secrets" in left menu
  5. Click on DEPLOYMENT-ACCESS-KEY
  6. Click "Show Secret Value"
  7. Copy the displayed value

Requires Permissions: You need "Key Vault Secrets User" or "Key Vault Administrator" role.

Method 3: Settings Page in Application​

If you've already logged in:

  1. Access your Alactic AGI instance
  2. Click Settings icon (gear) in top right
  3. Scroll to "Deployment Information" section
  4. Key is displayed (partially masked)
  5. Click "Copy" to copy full key

Note: You must be authenticated to access Settings page.

Method 4: SSH to VM (Advanced)​

SSH into the VM and read the environment file:

ssh -i your-key.pem your-user@your-vm-fqdn
cat ~/.env | grep DEPLOYMENT_ACCESS_KEY

Requires: SSH key for VM access

Viewing Key in Dashboard​

Once authenticated, your deployment key is visible in the Settings page.

Location in Interface​

  1. Log in to Alactic AGI
  2. Click the Settings icon (⚙️) in the top-right corner
  3. Scroll to Deployment Information card

What You See​

Deployment Access Key
ak-7f8e9d0c••••••••••••••••••••••••••5f6e

[Copy Key] [Show Full Key]

Security Feature: Key is partially masked by default. Click "Show Full Key" to reveal complete value.

Copying the Key​

Click the "Copy Key" button to copy the full key to clipboard. Useful for:

  • Sharing with team members
  • Configuring API clients
  • Setting up automation scripts
  • Documentation purposes

Key Immutability​

Critical Limitation: Deployment access keys cannot be changed after creation.

Why Keys Cannot Be Changed​

  • Generated during ARM template deployment
  • Embedded in multiple Azure resources
  • Changing would require redeployment
  • Intentional design for security and consistency

Implications​

  • Lost Key: Cannot retrieve if lost before first login
  • Compromised Key: Cannot rotate key without redeployment
  • Team Changes: Cannot revoke access for specific users
  • Audit Requirements: Cannot enforce key rotation policies

What This Means for You​

Before Deployment:

  • Ensure you can access deployment outputs
  • Have a secure place to store the key
  • Plan for key management and distribution

After Deployment:

  • Store key in password manager immediately
  • Share only with authorized personnel
  • Treat as a permanent credential
  • Document key location for disaster recovery

If You Need to Change the Key​

The only way to change the deployment access key is to redeploy:

  1. Export Data (if needed)

    • Back up any processed documents
    • Export Cosmos DB data if required

  2. Delete Deployment

    • Delete the entire resource group
    • Or delete all Alactic AGI resources individually

  3. Redeploy

Cost Impact: Redeployment may incur costs based on retained storage and data.

Security Best Practices​

Storing the Key​

DO:

  • Store in enterprise password manager (1Password, LastPass, Azure Key Vault)
  • Encrypt if storing in files or documentation
  • Use Azure Key Vault for programmatic access
  • Maintain offline backup in secure location

DON'T:

  • Commit to version control systems (Git, SVN)
  • Email unencrypted
  • Store in plain text files on local disk
  • Share via insecure messaging platforms

Sharing with Team Members​

Secure Sharing Methods:

  • Encrypted email (PGP, S/MIME)
  • Enterprise password manager with team vaults
  • Azure Key Vault with RBAC
  • Secure collaboration tools (SharePoint, Teams with DLP)

Insecure Sharing Methods:

  • Slack or Teams direct messages
  • SMS or text messages
  • Unencrypted email
  • Shared documents without encryption
  • Verbal communication

Access Control​

Since keys cannot be rotated, implement additional controls:

Application-Level

  • Use Azure AD for portal access
  • Implement IP whitelisting in NSG
  • Enable Azure Front Door with WAF
  • Add custom authentication layer

Network-Level

  • Restrict NSG to specific IP ranges
  • Use Azure Bastion for VM access
  • Deploy in private VNET
  • Implement VPN or ExpressRoute

Monitoring

  • Enable Azure Monitor for access logs
  • Set up alerts for unusual access patterns
  • Review audit logs regularly
  • Track login attempts and failures

API Access with Keys​

HTTP Header Format​

When making API requests, include the key in headers:

POST /api/start HTTP/1.1
Host: your-instance.com:3000
Content-Type: application/json
X-Deployment-Key: ak-7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e

{
  "urls": ["https://example.com"]
}

Header Name: X-Deployment-Key
Header Value: Full deployment key with ak- prefix

Query Parameter (EventSource Only)​

For Server-Sent Events (SSE) streaming endpoints:

GET /api/stream/job-id?key=ak-7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e HTTP/1.1
Host: your-instance.com:3000

Note: EventSource API doesn't support custom headers, so key is passed as query parameter.

cURL Examples​

Processing URLs:

curl -X POST https://your-instance.com:3000/api/start \
  -H "Content-Type: application/json" \
  -H "X-Deployment-Key: ak-your-key-here" \
  -d '{"urls": ["https://example.com"]}'

Checking Configuration:

curl https://your-instance.com:3000/api/config \
  -H "X-Deployment-Key: ak-your-key-here"

Uploading PDF:

curl -X POST https://your-instance.com:3000/api/upload \
  -H "X-Deployment-Key: ak-your-key-here" \
  -F "file=@document.pdf"

Troubleshooting Key Issues​

Invalid Key Error​

Symptom: "Invalid deployment key" message

Causes:

  • Typo in key (missing characters, wrong case)
  • Extra whitespace before/after key
  • Wrong key for this deployment
  • Backend service not initialized

Solutions:

  1. Copy key again from deployment outputs
  2. Verify no extra spaces
  3. Wait 2-3 minutes for backend initialization
  4. Check backend service status via SSH

Key Not in Deployment Outputs​

Symptom: deploymentAccessKey missing from outputs

Causes:

  • Deployment failed before completion
  • Custom template missing output definition
  • Viewing wrong deployment

Solutions:

  1. Check deployment status in Azure Portal
  2. Verify deployment completed successfully
  3. Use Key Vault method to retrieve key
  4. Contact support if issue persists

Browser Not Remembering Key​

Symptom: Must re-enter key after closing browser

Causes:

  • Browser in incognito/private mode
  • localStorage disabled
  • Browser cache cleared
  • Domain name changed

Solutions:

  1. Use normal browsing mode
  2. Enable localStorage in browser settings
  3. Re-enter key (it will persist in normal mode)
  4. Bookmark access gate with key in query (not recommended for security)

Multiple Deployments Confusion​

Symptom: Using key from wrong deployment

Solution: Create a naming convention:

Production: ak-xxxxx (stored in production password vault)
Staging: ak-yyyyy (stored in staging password vault)
Development: ak-zzzzz (stored in dev password vault)

Label each key clearly with environment and deployment date.

Key Management Workflow​

Initial Deployment​

  1. Complete Azure Marketplace deployment
  2. Immediately copy deploymentAccessKey from outputs
  3. Store in enterprise password manager
  4. Share with authorized team members via secure channel
  5. Document key location in runbook

Daily Operations​

  1. Users retrieve key from password manager
  2. Enter key once in browser
  3. Browser remembers key in localStorage
  4. No further authentication needed
  5. Key is sent automatically with all requests

Team Member Onboarding​

  1. Verify new member is authorized
  2. Grant access to Key Vault (Azure RBAC)
  3. Share key via secure method
  4. Document access grant in audit log
  5. Provide training on key security

Key Compromise Response​

If key is compromised:

  1. Immediate: Change NSG rules to block all traffic
  2. Short-term: Implement IP allowlist
  3. Long-term: Plan redeployment with new key
  4. Document: Incident report and lessons learned