API Key Management Overview

Overview

API keys provide secure, programmatic access to the ASCEND platform for SDK integrations, automation scripts, and third-party applications. ASCEND implements banking-level security for API key management with SHA-256 hashing, comprehensive audit trails, and configurable expiration policies.

API key management is available in the Settings section of ASCEND (not the Admin Console), accessible to users with Admin role or higher.

Prerequisites

• Admin or higher role
• Access to Settings > API Keys section
• Understanding of key security best practices

Key Concepts

API Key Structure

ASCEND API keys follow a standardized format:

owkai_{type}_{random_string}

Components:

• owkai_ - Platform prefix
• {type} - Key type (admin, sdk, service, etc.)
• {random_string} - Cryptographically random 16+ characters

Example: owkai_admin_tUsL7xK9mPqR4wZ2

Security Model

Feature	Implementation
Storage	SHA-256 hash with random salt
Display	Full key shown only once at creation
Transmission	HTTPS only, never in URLs
Validation	Constant-time comparison
Audit	Every operation logged

Key States

State	Description	Actions Available
Active	Normal operation	View, Revoke
Expired	Past expiration date	View, Revoke
Revoked	Manually disabled	View only

Step-by-Step Guide

Accessing API Key Management

1. Navigate to Settings (gear icon in sidebar)
2. Select the "API Keys" tab
3. View existing keys or generate new ones

Viewing Existing Keys

The key list displays:

• Key name and description
• Masked key prefix (first/last 4 characters)
• Creation date
• Expiration date (if set)
• Last used timestamp
• Status badge

Generating a New Key

1. Click "Generate New Key" button
2. Enter required information:
   • Name (required): Descriptive identifier
   • Description (optional): Purpose documentation
   • Expiration: Never or 30/60/90/180/365 days
3. Click "Generate"
4. Critical: Copy and securely store the displayed key
5. Click "I've Saved My Key" to dismiss

Revoking a Key

1. Find the key in the list
2. Click the revoke icon (trash)
3. Confirm revocation in the modal
4. Key is immediately disabled

Configuration Options

Option	Description	Default
Name	Human-readable identifier	Required
Description	Purpose/usage documentation	Optional
Expires In	Days until expiration	90 days

Expiration Options

Option	Days	Use Case
Never	-	Service accounts, long-term integrations
30 days	30	Short-term testing
60 days	60	Development cycles
90 days	90	Standard production (recommended)
180 days	180	Extended integrations
365 days	365	Annual rotation schedule

Security Features

SHA-256 Hashing

API keys are never stored in plaintext:

Stored: sha256(key + salt)
Salt: Cryptographically random per key

Implications:

• Lost keys cannot be recovered
• Key must be stored at creation time
• Support cannot retrieve forgotten keys

Key Masking

In the UI and API responses, keys are masked:

Full key:   owkai_admin_tUsL7xK9mPqR4wZ2
Displayed:  owkai_admin_tUsL...4wZ2

Audit Trail

Every key operation is logged:

Event	Logged Data
Generate	User, timestamp, IP, key name
Revoke	User, timestamp, IP, key ID
Use	Timestamp, endpoint, response code

Rate Limiting

API key requests are rate limited:

Endpoint Type	Limit
Read operations	100/minute
Write operations	30/minute
Key generation	10/minute
Authentication	20/minute

API Key Usage

Authentication Methods

Authorization Header (Recommended):

curl -H "Authorization: Bearer owkai_admin_tUsL7xK9mPqR4wZ2" \
  https://api.ascend.ai/v1/agents

X-API-Key Header:

curl -H "X-API-Key: owkai_admin_tUsL7xK9mPqR4wZ2" \
  https://api.ascend.ai/v1/agents

SDK Configuration

Python SDK:

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_admin_tUsL7xK9mPqR4wZ2",
    organization_id="acme-corp"
)

Node.js SDK:

const { AscendClient } = require('@ascend-ai/sdk');

const client = new AscendClient({
    apiKey: 'owkai_admin_tUsL7xK9mPqR4wZ2',
    organizationId: 'acme-corp'
});

Best Practices

1. One Key Per Integration

   • Create separate keys for each application
   • Never share keys between services
   • Name keys descriptively

2. Regular Rotation

   • Establish a rotation schedule (90 days recommended)
   • Plan key rotation before expiration
   • Overlap validity periods during rotation

3. Secure Storage

   • Use secret management systems (Vault, AWS Secrets Manager)
   • Never store keys in source code
   • Never log API keys

4. Immediate Revocation

   • Revoke compromised keys immediately
   • Revoke keys for decommissioned services
   • Audit key usage before revocation

5. Monitoring

   • Review key usage statistics regularly
   • Monitor for unusual access patterns
   • Set up alerts for key events

API Reference

List API Keys

GET /api/keys/list
Authorization: Bearer <session_token>

Response:

{
  "keys": [
    {
      "id": 1,
      "name": "Production SDK",
      "key_prefix": "owkai_admin_tUsL...4wZ2",
      "description": "Main production integration",
      "created_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-04-01T00:00:00Z",
      "last_used_at": "2026-01-15T14:30:00Z",
      "status": "active"
    }
  ]
}

Generate API Key

POST /api/keys/generate
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "name": "CI/CD Pipeline",
  "description": "GitHub Actions deployment",
  "expires_in_days": 90
}

Response:

{
  "api_key": "owkai_admin_tUsL7xK9mPqR4wZ2",
  "key_id": 2,
  "name": "CI/CD Pipeline",
  "expires_at": "2026-04-20T00:00:00Z",
  "message": "Store this key securely. It will not be shown again."
}

Revoke API Key

DELETE /api/keys/{key_id}/revoke
Authorization: Bearer <session_token>

Response:

{
  "success": true,
  "message": "API key revoked successfully"
}

Get Key Usage Statistics

GET /api/keys/{key_id}/usage
Authorization: Bearer <session_token>

Response:

{
  "key_id": 1,
  "total_requests": 15420,
  "requests_24h": 342,
  "last_used": "2026-01-15T14:30:00Z",
  "top_endpoints": [
    {"endpoint": "/api/agents", "count": 5234},
    {"endpoint": "/api/alerts", "count": 3456}
  ]
}

Compliance Mapping

Requirement	Standard	Implementation
Key hashing	PCI-DSS 8.3.1	SHA-256 with salt
Audit logging	SOC 2 CC6.1	All operations logged
Key rotation	NIST 800-57	Configurable expiration
Access control	HIPAA 164.312(d)	Role-based key management

Troubleshooting

Key Not Working

Issue	Cause	Solution
401 Unauthorized	Invalid key	Verify key is correct
401 Unauthorized	Key expired	Generate new key
401 Unauthorized	Key revoked	Generate new key
403 Forbidden	Wrong organization	Use key for correct org

Key Generation Fails

Issue	Cause	Solution
Rate limited	Too many requests	Wait 1 minute
Missing name	Validation error	Provide key name
Permission denied	Insufficient role	Requires Admin role

Related

• API Key Management - Detailed operations guide
• SDK Integration - Using keys with SDKs
• Security Best Practices - Key security guidelines