Authentication Overview

Overview

ASCEND provides enterprise-grade authentication with multiple methods to support different use cases: interactive users (web UI), programmatic access (SDK/API), and automated pipelines (CI/CD). All authentication methods implement fail-secure behavior - any authentication failure results in access denial.

Why It Matters

Authentication is the first line of defense for your AI governance platform. ASCEND's authentication system:

Prevents unauthorized access to AI agent controls and sensitive configuration
Supports compliance requirements for SOC 2, HIPAA, and PCI-DSS
Enables audit trails by associating all actions with authenticated identities
Scales across use cases from single-user to enterprise multi-tenant deployments

Architecture

Authentication Flow Overview

+-------------------+     +-------------------+     +-------------------+
|                   |     |                   |     |                   |
|   Web UI User     |     |   SDK Client      |     |   CI/CD Pipeline  |
|                   |     |                   |     |                   |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                         |
         v                         v                         v
+--------+----------+     +--------+----------+     +--------+----------+
|   AWS Cognito     |     |   API Key Auth    |     |   API Key Auth    |
|   (JWT Tokens)    |     |   (X-API-Key)     |     |   (Bearer Token)  |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                         |
         +------------+------------+------------+------------+
                      |                         |
                      v                         v
              +-------+--------+       +-------+--------+
              |  JWT Validator |       |  API Key       |
              |  (RS256/JWKS)  |       |  Validator     |
              +-------+--------+       +-------+--------+
                      |                         |
                      +------------+------------+
                                   |
                                   v
                           +-------+--------+
                           |  RLS Context   |
                           |  (org_id set)  |
                           +-------+--------+
                                   |
                                   v
                           +-------+--------+
                           |  RBAC Check    |
                           |  (permissions) |
                           +----------------+

Authentication Methods Comparison

Method	Use Case	Token Type	Expiration	Best For
AWS Cognito	Web UI	JWT (RS256)	1 hour	Interactive users
API Keys	SDK/API	Hash-verified	Configurable	Programmatic access
Dual Auth	Mixed	JWT or API Key	Varies	Flexible endpoints

Supported Authentication Methods

1. AWS Cognito (Web UI)

Primary authentication for interactive users.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Features:

RS256 JWT signature validation
JWKS automatic key rotation
Multi-pool support (platform + per-org)
MFA support via Cognito
Session management with token refresh

Full Cognito Documentation

2. API Key Authentication (SDK/CI-CD)

For programmatic access via SDK or automated pipelines.

# Option 1: Bearer token
Authorization: Bearer owkai_admin_xxxxxxxxxxxxx...

# Option 2: X-API-Key header
X-API-Key: owkai_admin_xxxxxxxxxxxxx...

Features:

SHA-256 hashed storage (never plaintext)
Constant-time comparison (timing attack prevention)
Per-key rate limiting
Usage tracking and audit logging
Configurable expiration

Full API Key Documentation

3. Dual Authentication

Endpoints that accept either Cognito JWT or API Key.

The system automatically detects the authentication method:

JWT format (3 dot-separated parts): Use Cognito validation
API key format (prefix + key): Use API key validation

# FastAPI dependency for dual auth
async def get_current_user_or_api_key(
    request: Request,
    db: Session = Depends(get_db)
) -> dict:
    # Automatically detects and validates JWT or API key
    pass

Configuration

Environment Variables

# Cognito Configuration
COGNITO_REGION=us-east-2
COGNITO_USER_POOL_ID=us-east-2_xxxxxxxxx
COGNITO_APP_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
ENABLE_TWO_POOL_AUTH=false

# Brute Force Protection
MAX_LOGIN_ATTEMPTS_PER_IP=5
MAX_LOGIN_ATTEMPTS_PER_EMAIL=10
LOGIN_ATTEMPT_WINDOW_MINUTES=15

# Session Configuration
ACCESS_TOKEN_EXPIRY_HOURS=1
REFRESH_TOKEN_EXPIRY_DAYS=30

Organization-Level Settings

Each organization can customize authentication behavior:

{
  "auth_config": {
    "mfa_required": true,
    "session_timeout_minutes": 60,
    "allowed_ip_ranges": ["10.0.0.0/8", "192.168.0.0/16"],
    "api_key_max_age_days": 90,
    "password_policy": {
      "min_length": 12,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_special": true,
      "history_count": 12
    }
  }
}

Security Features

Brute Force Protection

Protection	Threshold	Window	Action
IP-based	5 failures	15 minutes	Block IP
Email-based	10 failures	15 minutes	Block email
Account lockout	Configurable	Configurable	Exponential backoff

Token Security

Feature	Implementation	Purpose
RS256 Signatures	RSA public key verification	Prevents token forgery
JWKS Rotation	Automatic key refresh	Enables key rotation without downtime
Token Revocation	Database-tracked JTIs	Immediate invalidation capability
Short Expiration	1-hour access tokens	Limits exposure window

API Key Security

Feature	Implementation	Purpose
SHA-256 Hashing	Salted hash storage	Never stores plaintext
Constant-Time Compare	`secrets.compare_digest()`	Prevents timing attacks
32-Char Prefix	Collision-resistant lookup	Enables efficient search
Usage Tracking	Per-request logging	Audit and analytics

Fail-Secure Behavior

All authentication failures result in DENY:

Scenario	Response	HTTP Status
Missing Authorization header	"Missing Authorization header"	401
Invalid JWT signature	"Invalid authentication token"	401
Expired JWT	"Token has expired"	401
Revoked token	"Token has been revoked"	401
Invalid API key	"Invalid API key"	401
Expired API key	"API key expired"	401
Rate limited	"Rate limit exceeded"	429
Cognito unavailable	"Authentication service unavailable"	503

Compliance Mapping

Framework	Control	ASCEND Implementation
SOC 2	CC6.1	JWT validation, API key hashing, brute force protection
HIPAA	164.312(d)	Person or entity authentication via Cognito
PCI-DSS	Req 8.1	Unique user identification
PCI-DSS	Req 8.2	Strong authentication (passwords, MFA)
PCI-DSS	Req 8.3	Two-factor authentication support
NIST 800-63	AAL2	Multi-factor authentication capability
NIST 800-63	AAL3	Cryptographic token validation (RS256)

Verification

Test Cognito Authentication

# Login and get token
curl -X POST https://api.ascend.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

# Use token for API request
curl -X GET https://api.ascend.io/v1/agents \
  -H "Authorization: Bearer $JWT_TOKEN"

Test API Key Authentication

# Using Bearer token format
curl -X GET https://api.ascend.io/v1/agents \
  -H "Authorization: Bearer owkai_admin_xxxxxxxxxxxxx"

# Using X-API-Key header
curl -X GET https://api.ascend.io/v1/agents \
  -H "X-API-Key: owkai_admin_xxxxxxxxxxxxx"

Verify Authentication Status

curl -X GET https://api.ascend.io/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "user_id": 123,
  "email": "user@example.com",
  "organization_id": 1,
  "organization_name": "Acme Corp",
  "role": "admin",
  "auth_method": "cognito",
  "permissions": ["dashboard.view", "alerts.acknowledge", ...]
}

Next Steps

AWS Cognito Integration - Detailed Cognito configuration
JWT Token Management - JWT validation and claims
API Key Authentication - SDK and CI/CD authentication
Authorization Overview - RBAC and permissions

Overview​

Why It Matters​

Architecture​

Authentication Flow Overview​

Authentication Methods Comparison​

Supported Authentication Methods​

1. AWS Cognito (Web UI)​

2. API Key Authentication (SDK/CI-CD)​

3. Dual Authentication​

Configuration​

Environment Variables​

Organization-Level Settings​

Security Features​

Brute Force Protection​

Token Security​

API Key Security​

Fail-Secure Behavior​

Compliance Mapping​

Verification​

Test Cognito Authentication​

Test API Key Authentication​

Verify Authentication Status​

Next Steps​