Skip to main content

Authentication

Secure your API requests with proper authentication methods supported by Alactic AGI.

API Key Authentication​

Getting Your API Key​

  1. Sign in to Azure Portal
  2. Navigate to your Alactic AGI resource
  3. Go to Keys and Endpoints section
  4. Copy your primary or secondary key

Using API Keys​

Include your API key in the Authorization header of every request:

curl -X POST https://your-deployment.azurewebsites.net/api/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document": "base64_encoded_content"}'

Best Practices​

Key Security

  • Never commit API keys to version control
  • Store keys in environment variables or secure vaults
  • Rotate keys periodically (recommended: every 90 days)
  • Use separate keys for development and production
  • Revoke compromised keys immediately

Key Management

  • Use Azure Key Vault for enterprise deployments
  • Implement key rotation procedures
  • Monitor key usage through Azure Portal
  • Set up alerts for unusual activity
  • Document key ownership and access

Header Format​

Required Headers​

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Optional Headers​

X-Request-ID: unique-request-identifier
X-Client-Version: your-app-version
User-Agent: YourApp/1.0

Authentication Errors​

Invalid API Key​

Status Code: 401 Unauthorized

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid or has been revoked",
  "code": "AUTH_001"
}

Solutions:

  • Verify key is correctly copied
  • Check key hasn't been rotated
  • Ensure no extra spaces or characters
  • Confirm key is for correct environment

Expired Key​

Status Code: 401 Unauthorized

{
  "error": "Expired API key",
  "message": "The API key has expired and needs to be renewed",
  "code": "AUTH_002"
}

Solutions:

  • Generate new key in Azure Portal
  • Update your application configuration
  • Implement automatic key rotation

Missing Authorization​

Status Code: 401 Unauthorized

{
  "error": "Missing authorization",
  "message": "Authorization header is required",
  "code": "AUTH_003"
}

Solutions:

  • Add Authorization header to request
  • Verify header name is spelled correctly
  • Check header value format is correct

Rate Limiting​

Rate Limit Headers​

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Rate Limit Exceeded​

Status Code: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your plan's rate limit",
  "retry_after": 60,
  "code": "RATE_001"
}

Solutions:

  • Implement exponential backoff
  • Upgrade to higher tier plan
  • Optimize request patterns
  • Use batch endpoints where available

SDK Authentication​

Python​

from alactic import AlacticClient

# From environment variable
import os
client = AlacticClient(
    api_key=os.getenv('ALACTIC_API_KEY')
)

# From Azure Key Vault
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
vault_client = SecretClient(
    vault_url="https://your-vault.vault.azure.net/",
    credential=credential
)
api_key = vault_client.get_secret("alactic-api-key").value
client = AlacticClient(api_key=api_key)

Node.js​

const { AlacticClient } = require('alactic-sdk');

// From environment variable
const client = new AlacticClient({
  apiKey: process.env.ALACTIC_API_KEY
});

// From Azure Key Vault
const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const vaultClient = new SecretClient(
  "https://your-vault.vault.azure.net/",
  credential
);

async function initClient() {
  const secret = await vaultClient.getSecret("alactic-api-key");
  const client = new AlacticClient({ apiKey: secret.value });
  return client;
}

C#​

using Alactic.SDK;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// From environment variable
var apiKey = Environment.GetEnvironmentVariable("ALACTIC_API_KEY");
var client = new AlacticClient(apiKey);

// From Azure Key Vault
var kvUri = "https://your-vault.vault.azure.net/";
var credential = new DefaultAzureCredential();
var secretClient = new SecretClient(new Uri(kvUri), credential);
var secret = await secretClient.GetSecretAsync("alactic-api-key");
var client = new AlacticClient(secret.Value.Value);

Environment-Specific Keys​

Development Environment​

# .env.development
ALACTIC_API_KEY=dev_key_xxxxxxxxxxxxx
ALACTIC_ENDPOINT=https://dev-deployment.azurewebsites.net

Production Environment​

# .env.production
ALACTIC_API_KEY=prod_key_xxxxxxxxxxxxx
ALACTIC_ENDPOINT=https://prod-deployment.azurewebsites.net

Configuration Management​

import os
from dataclasses import dataclass

@dataclass
class AlacticConfig:
    api_key: str
    endpoint: str
    
    @classmethod
    def from_env(cls):
        return cls(
            api_key=os.getenv('ALACTIC_API_KEY'),
            endpoint=os.getenv('ALACTIC_ENDPOINT')
        )

# Usage
config = AlacticConfig.from_env()
client = AlacticClient(
    api_key=config.api_key,
    endpoint=config.endpoint
)

Security Recommendations​

Production Checklist​

  • Store API keys in Azure Key Vault or equivalent
  • Enable Azure Key Vault soft delete and purge protection
  • Use managed identities where possible
  • Implement least privilege access
  • Enable audit logging for key access
  • Set up monitoring and alerts
  • Rotate keys on a schedule
  • Use separate keys per environment
  • Never log API keys
  • Implement key expiration policies

Network Security​

  • Use HTTPS only (enforced by default)
  • Implement IP whitelisting if available
  • Use Azure Private Link for enhanced security
  • Enable Azure DDoS Protection
  • Configure Web Application Firewall rules

Compliance​

  • Follow your organization's security policies
  • Maintain key inventory and ownership records
  • Document key rotation procedures
  • Implement audit trails
  • Regular security reviews

Testing Authentication​

Verify API Key​

curl -X GET https://your-deployment.azurewebsites.net/api/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

{
  "valid": true,
  "plan": "Pro",
  "expires_at": "2026-12-19T00:00:00Z",
  "rate_limit": 1000
}

Health Check​

curl -X GET https://your-deployment.azurewebsites.net/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Additional Resources​