API Key Management

Overview

This guide provides detailed instructions for managing API keys in ASCEND, including generating new keys, monitoring usage, and securely revoking keys when necessary. API keys enable programmatic access to the ASCEND API for SDK integrations, automation, and third-party applications.

Prerequisites

Admin role or higher
Access to Settings section
Secure storage solution for generated keys

Step-by-Step Guide

Generating a New API Key

Access the API Key Section
- Click the Settings icon (gear) in the sidebar
- Select the "API Keys" tab
- Click the "Generate New Key" button
Configure Key Properties

Name (Required)
- Enter a descriptive name
- Best practice: Include purpose and environment
- Examples:
  - "Production - Main Backend Service"
  - "Development - Local Testing"
  - "CI/CD - GitHub Actions"
Description (Optional)
- Document the key's purpose
- Include owner/team information
- Note any specific permissions or restrictions
Expiration (Required)
- Select from dropdown:
  - Never expires
  - 30 days
  - 60 days
  - 90 days (recommended)
  - 180 days
  - 365 days
Generate the Key
- Click "Generate" button
- Wait for the key to be created
Save the Key Securely

Critical Warning:
- The full API key is displayed only once
- It cannot be recovered after you dismiss the dialog
- Copy immediately to a secure location
Copy Options:
- Click the "Copy" button to copy to clipboard
- Verify the key was copied correctly
- Store in your secret management system
Confirm Storage
- Click "I've Saved My Key" button
- The dialog closes
- Key appears in the list with masked value

Viewing API Keys

The API key list displays all keys for your organization:

Column	Description
Name	Key identifier you provided
Key	Masked prefix and suffix
Description	Purpose documentation
Created	Generation timestamp
Expires	Expiration date or "Never"
Last Used	Most recent API call
Status	Active, Expired, or Revoked
Actions	View usage, Revoke

Viewing Key Usage Statistics

Access Usage Stats
- Find the key in the list
- Click the "View Activity" icon (graph)
- Modal displays usage statistics
Available Metrics
- Total requests (all time)
- Requests in last 24 hours
- Requests in last 7 days
- Last used timestamp
- Top endpoints by request count
- Error rate
Usage Insights
- Identify unused keys
- Detect unusual activity
- Plan key rotation timing

Revoking an API Key

Initiate Revocation
- Find the key in the list
- Click the revoke icon (trash)
- Confirmation modal appears
Confirm Revocation
- Review the key name
- Understand the impact:
  - Immediate effect
  - Cannot be undone
  - All applications using this key will fail
- Click "Revoke Key"
Post-Revocation
- Key status changes to "Revoked"
- Key remains visible for audit purposes
- Audit log records the revocation

Rotating API Keys

Follow this process to safely rotate keys:

Generate New Key
- Create new key with descriptive name
- Include "rotation" or date in name
- Set appropriate expiration
Update Applications
- Deploy new key to applications
- Update secret management systems
- Verify applications work with new key
Monitor Transition
- Watch usage stats on both keys
- Confirm old key usage drops to zero
- Allow overlap period (24-48 hours)
Revoke Old Key
- Once old key shows no usage
- Revoke the old key
- Document rotation in change log

Configuration Options

Key Generation Options

Option	Description	Default	Constraints
name	Key identifier	Required	1-255 characters
description	Purpose documentation	Optional	0-500 characters
expires_in_days	Days until expiration	90	null, 30, 60, 90, 180, 365

Key Properties

Property	Description	Mutable
id	Unique identifier	No
name	Display name	No
description	Purpose	No
key_prefix	Masked key	No
created_at	Creation time	No
expires_at	Expiration time	No
last_used_at	Last API call	Auto-updated
status	Current state	Via revocation

API Reference

Generate API Key

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

{
  "name": "Production Backend",
  "description": "Main production service API access",
  "expires_in_days": 90
}

Response:

{
  "api_key": "owkai_admin_tUsL7xK9mPqR4wZ2",
  "key_id": 1,
  "name": "Production Backend",
  "description": "Main production service API access",
  "expires_at": "2026-04-20T00:00:00Z",
  "message": "Store this key securely. It will not be shown again."
}

List API Keys

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

Response:

{
  "keys": [
    {
      "id": 1,
      "name": "Production Backend",
      "key_prefix": "owkai_admin_tUsL...4wZ2",
      "description": "Main production service API access",
      "created_at": "2026-01-20T10:30:00Z",
      "expires_at": "2026-04-20T10:30:00Z",
      "last_used_at": "2026-01-20T14:22:15Z",
      "status": "active",
      "total_requests": 1542
    }
  ],
  "total": 1
}

Get Key Usage

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

Response:

{
  "key_id": 1,
  "key_name": "Production Backend",
  "usage": {
    "total_requests": 1542,
    "requests_24h": 156,
    "requests_7d": 892,
    "requests_30d": 1542,
    "error_count": 12,
    "error_rate": 0.78
  },
  "last_used": "2026-01-20T14:22:15Z",
  "top_endpoints": [
    {"endpoint": "POST /api/agents/actions", "count": 823},
    {"endpoint": "GET /api/alerts", "count": 412},
    {"endpoint": "GET /api/policies", "count": 307}
  ],
  "daily_usage": [
    {"date": "2026-01-20", "requests": 156},
    {"date": "2026-01-19", "requests": 178}
  ]
}

Revoke API Key

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

Response:

{
  "success": true,
  "message": "API key revoked successfully",
  "key_id": 1,
  "revoked_at": "2026-01-20T15:00:00Z"
}

Best Practices

Key Naming Conventions

Use consistent naming patterns:

{environment}_{service}_{purpose}

Examples:

prod_backend_main - Production backend main key
dev_frontend_local - Development frontend local testing
staging_cicd_github - Staging CI/CD GitHub Actions

Secure Storage

Recommended Storage Solutions:

Solution	Best For
AWS Secrets Manager	AWS deployments
HashiCorp Vault	Multi-cloud, on-premise
Azure Key Vault	Azure deployments
GCP Secret Manager	GCP deployments
1Password/Bitwarden	Small teams

Never Store Keys In:

Source code repositories
Configuration files (committed)
Environment variables (in plain text)
Log files
Chat messages or emails
Shared documents

Rotation Schedule

Environment	Rotation Frequency	Expiration
Production	90 days	90 days
Staging	60 days	60 days
Development	30 days	30 days
CI/CD	90 days	90 days

Access Control

Limit key generation to Admin role
Require approval for production keys
Document who has access to each key
Audit key usage regularly

Troubleshooting

Cannot Generate Key

Issue	Cause	Solution
Button disabled	Missing required field	Enter key name
403 Forbidden	Insufficient role	Requires Admin role
Rate limited	Too many attempts	Wait 1 minute
500 Error	Server issue	Try again, contact support

Key Not Working

Issue	Cause	Solution
401 Invalid key	Typo in key	Verify key is correct
401 Expired	Past expiration	Generate new key
401 Revoked	Key was revoked	Generate new key
403 Wrong org	Organization mismatch	Use correct key for org

Cannot Revoke Key

Issue	Cause	Solution
403 Forbidden	Not key owner	Admin can revoke any key
404 Not found	Invalid key ID	Verify key exists
Already revoked	Double revocation	Key already inactive

Lost API Key

Unfortunately, lost keys cannot be recovered.

Recovery process:

Generate a new key
Update all applications
Revoke the lost key (if you know which one)
Monitor for unauthorized usage

Security Incident Response

If a Key is Compromised

Immediate Revocation
- Revoke the key immediately
- Do not wait to verify
Impact Assessment
- Review key usage logs
- Identify unauthorized access
- Determine data exposure
Generate Replacement
- Create new key
- Deploy to legitimate applications
Incident Documentation
- Record timeline
- Document scope
- Note remediation steps
Post-Incident Review
- Analyze root cause
- Implement preventive measures
- Update security procedures

API Key Overview - Key concepts and security
SDK Integration - Using keys with SDKs
Security Best Practices - Overall security guidance

Overview​

Prerequisites​

Step-by-Step Guide​

Generating a New API Key​

Viewing API Keys​

Viewing Key Usage Statistics​

Revoking an API Key​

Rotating API Keys​

Configuration Options​

Key Generation Options​

Key Properties​

API Reference​

Generate API Key​

List API Keys​

Get Key Usage​

Revoke API Key​

Best Practices​

Key Naming Conventions​

Secure Storage​

Rotation Schedule​

Access Control​

Troubleshooting​

Cannot Generate Key​

Key Not Working​

Cannot Revoke Key​

Lost API Key​

Security Incident Response​

If a Key is Compromised​

Related​

Overview

Prerequisites

Step-by-Step Guide

Generating a New API Key

Viewing API Keys

Viewing Key Usage Statistics

Revoking an API Key

Rotating API Keys

Configuration Options

Key Generation Options

Key Properties

API Reference

Generate API Key

List API Keys

Get Key Usage

Revoke API Key

Best Practices

Key Naming Conventions

Secure Storage

Rotation Schedule

Access Control

Troubleshooting

Cannot Generate Key

Key Not Working

Cannot Revoke Key

Lost API Key

Security Incident Response

If a Key is Compromised

Related