Installation

ASCEND Authorization Center provides SDKs and REST API integration options.

Integration Methods

Method	Use Case	Complexity
Python SDK	Install via pip	Low
Direct REST API	Custom integration	Medium

System Requirements

• Python: 3.9+ with requests library
• Node.js: 18+ with axios or fetch
• Network: HTTPS outbound to pilot.owkai.app (port 443)
• Authentication: API key from ASCEND dashboard

Method 1: SDK Installation (Recommended)

Python

# Install the ASCEND SDK
pip install ascend-ai-sdk

# Set environment variables (use your actual key from Dashboard)
export ASCEND_API_KEY="owkai_admin_xK9mNpQrStUvWxYzAbCdEfGh..."
export ASCEND_API_URL="https://pilot.owkai.app"

Node.js

# Install the ASCEND SDK
npm install @ascend-ai/sdk

# Set environment variables (use your actual key from Dashboard)
export ASCEND_API_KEY="owkai_admin_xK9mNpQrStUvWxYzAbCdEfGh..."
export ASCEND_API_URL="https://pilot.owkai.app"

Method 2: Direct REST API

Minimal Python Client

import os
import requests
from typing import Dict, Optional

class AscendClient:
    """
    Minimal ASCEND Authorization Center client.
    """

    def __init__(
        self,
        api_url: Optional[str] = None,
        api_key: Optional[str] = None,
        timeout: int = 30
    ):
        self.api_url = api_url or os.getenv('ASCEND_API_URL', 'https://pilot.owkai.app')
        self.api_key = api_key or os.getenv('ASCEND_API_KEY')
        self.timeout = timeout

        if not self.api_key:
            raise ValueError("API key required. Set ASCEND_API_KEY environment variable.")

        # Authentication headers
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}",
            "User-Agent": "AscendClient/2.0 Python"
        }

    def submit_action(self, **action_data) -> Dict:
        """
        Submit agent action for authorization.

        Required fields: agent_id, action_type, description, tool_name
        Endpoint: POST /api/v1/actions/submit
        Source: /ow-ai-backend/routes/actions_v1_routes.py:251
        """
        url = f"{self.api_url}/api/v1/actions/submit"

        response = requests.post(
            url,
            headers=self.headers,
            json=action_data,
            timeout=self.timeout
        )
        response.raise_for_status()
        return response.json()

    def get_action_status(self, action_id: int) -> Dict:
        """
        Get current status of an action.

        Endpoint: GET /api/v1/actions/{action_id}/status
        Source: /ow-ai-backend/routes/actions_v1_routes.py:1111
        """
        url = f"{self.api_url}/api/v1/actions/{action_id}/status"

        response = requests.get(
            url,
            headers=self.headers,
            timeout=10  # Status checks are fast
        )
        response.raise_for_status()
        return response.json()

    def test_connection(self) -> Dict:
        """Test API connectivity and authentication"""
        try:
            # Health check
            response = requests.get(f"{self.api_url}/health", timeout=5)
            response.raise_for_status()

            # Verify authentication
            response = requests.get(
                f"{self.api_url}/api/deployment-info",
                headers=self.headers,
                timeout=5
            )
            response.raise_for_status()

            return {
                "status": "connected",
                "api_version": response.json().get("version", "unknown")
            }
        except Exception as e:
            return {
                "status": "error",
                "error": str(e)
            }

Minimal Node.js Client

/**
 * Minimal ASCEND Authorization Center client.
 *
 */
const axios = require('axios');

class AscendClient {
  constructor(options = {}) {
    this.apiUrl = options.apiUrl || process.env.ASCEND_API_URL || 'https://pilot.owkai.app';
    this.apiKey = options.apiKey || process.env.ASCEND_API_KEY;
    this.timeout = options.timeout || 30000;

    if (!this.apiKey) {
      throw new Error('API key required. Set ASCEND_API_KEY environment variable.');
    }

    // Authentication headers
    // Source: /ow-ai-backend/routes/authorization_routes.py:2219
    this.headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.apiKey}`,
      'User-Agent': 'AscendClient/2.0 Node'
    };
  }

  /**
   * Submit agent action for authorization.
   *
   * Endpoint: POST /api/v1/actions/submit
   * Source: /ow-ai-backend/routes/authorization_routes.py:2202-2395
   */
  async submitAction(actionData) {
    const response = await axios.post(
      `${this.apiUrl}/api/v1/actions/submit`,
      actionData,
      { headers: this.headers, timeout: this.timeout }
    );
    return response.data;
  }

  /**
   * Get current status of an action.
   *
   * Endpoint: GET /api/v1/actions/{action_id}/status
   * Source: /ow-ai-backend/routes/agent_routes.py:691-721
   */
  async getActionStatus(actionId) {
    const response = await axios.get(
      `${this.apiUrl}/api/v1/actions/${actionId}/status`,
      { headers: this.headers, timeout: 10000 }
    );
    return response.data;
  }

  /**
   * Test API connectivity and authentication
   */
  async testConnection() {
    try {
      // Health check
      await axios.get(`${this.apiUrl}/health`, { timeout: 5000 });

      // Verify authentication
      const response = await axios.get(
        `${this.apiUrl}/api/deployment-info`,
        { headers: this.headers, timeout: 5000 }
      );

      return {
        status: 'connected',
        apiVersion: response.data.version || 'unknown'
      };
    } catch (error) {
      return {
        status: 'error',
        error: error.message
      };
    }
  }
}

module.exports = { AscendClient };

Environment Configuration

.env File (Recommended)

# Required - your key from Dashboard (format: owkai_{role}_{random})
ASCEND_API_KEY=owkai_admin_xK9mNpQrStUvWxYzAbCdEfGhIjKlMnOp...

# Optional (defaults shown)
ASCEND_API_URL=https://pilot.owkai.app
ASCEND_TIMEOUT=30

API Key Format

Your API key prefix reflects your role:

• owkai_super_admin_... - Super Admin access
• owkai_admin_... - Admin access
• owkai_user_... - Standard user access

The full key is shown only once at creation. Store it securely!

Python: Load Environment Variables

from dotenv import load_dotenv
import os

load_dotenv()

client = AscendClient(
    api_key=os.getenv('ASCEND_API_KEY'),
    api_url=os.getenv('ASCEND_API_URL')
)

Node.js: Load Environment Variables

require('dotenv').config();

const client = new AscendClient({
  apiKey: process.env.ASCEND_API_KEY,
  apiUrl: process.env.ASCEND_API_URL
});

Verify Installation

Python

from ascend import AscendClient

client = AscendClient()
status = client.test_connection()

if status['status'] == 'connected':
    print(f"✅ Connected to ASCEND (version: {status['api_version']})")
else:
    print(f"❌ Connection failed: {status['error']}")

Node.js

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

(async () => {
  const client = new AscendClient();
  const status = await client.testConnection();

  if (status.status === 'connected') {
    console.log(`✅ Connected to ASCEND (version: ${status.apiVersion})`);
  } else {
    console.log(`❌ Connection failed: ${status.error}`);
  }
})();

Integration Examples

See the full SDK documentation for complete working examples:

SDK	Package	Documentation
Python SDK	ascend-ai-sdk	Python SDK Guide
Node.js SDK	@ascend-ai/sdk	Node.js SDK Guide
REST API	Direct HTTP	REST API Reference

Troubleshooting

Connection Issues

# Test with verbose logging
import logging
logging.basicConfig(level=logging.DEBUG)

client = AscendClient(debug=True)
status = client.test_connection()

SSL Certificate Errors

# Python: Update certifi
pip install --upgrade certifi requests

# Node.js: Use system CA
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

Firewall Rules

Ensure outbound HTTPS (port 443) access to:

• pilot.owkai.app (API endpoint)

Next Steps

• Authentication - API key management
• First Agent Action - Submit your first action
• Integration Examples - Working code examples