API Access

Enable API access to integrate CastellanAI with your existing tools and workflows.

Dashboard First

Most users don't need API access. The CastellanAI dashboard provides all features for day-to-day security monitoring.

---

Overview

CastellanAI provides API access for organizations integrating security data with SIEM platforms, ticketing systems, or custom dashboards.

---

Who Needs API Access?

User Type	Use Case
IT Teams	Integrating with existing security tools
SOC Teams	Pulling data into centralized SIEM platforms
Developers	Building custom integrations or automations

---

Enabling API Access

1️⃣ Navigate

Step 1: Navigate to API Settings

1. Log in to the CastellanAI Portal
2. Click your profile icon in the top-right corner
3. Select Settings → API Access

2️⃣ Create Key

Step 2: Create an API Key

1. Click + Create API Key
2. Enter a descriptive name (e.g., "SIEM Integration" or "Ticketing System")
3. Select the appropriate permission level:

Permission	What It Allows
Read Only	View security events, agent status, and reports
Read/Write	Read access plus ability to acknowledge events
Admin	Full access including configuration changes

4. Click Create Key

3️⃣ Save Key

Step 3: Save Your Key

One-Time Display

Your API key is shown only once. Copy it immediately and store it securely (e.g., in a password manager or secrets vault).

Storage Best Practices:

• Use a password manager
• Store in a secrets vault (e.g., HashiCorp Vault, AWS Secrets Manager)
• Never commit API keys to version control

---

API Key Permissions

👁️ Read Only

Read Only Permission

Use Case: Monitoring and reporting integrations

Capabilities:

Action	Allowed
View security events	✅
View agent status	✅
Generate reports	✅
Acknowledge events	❌
Modify configuration	❌

✏️ Read/Write

Read/Write Permission

Use Case: Ticketing and workflow integrations

Capabilities:

Action	Allowed
View security events	✅
View agent status	✅
Generate reports	✅
Acknowledge events	✅
Execute actions	✅
Modify configuration	❌

👑 Admin

Admin Permission

Use Case: Full automation and management

Capabilities:

Action	Allowed
All Read/Write capabilities	✅
Modify configuration	✅
Manage users	✅
Create/delete API keys	✅

Use Sparingly

Only use Admin permission when absolutely necessary. Prefer least-privilege access.

---

Managing API Keys

👀 View Keys

View Active Keys

Go to Settings → API Access to see all active API keys:

Column	Description
Name	Key identifier
Permission	Access level
Created	Creation date
Last Used	Most recent API call

🗑️ Revoke Key

Revoke a Key

If a key is compromised or no longer needed:

1. Go to Settings → API Access
2. Find the key you want to revoke
3. Click the Revoke button
4. Confirm the action

Immediate Effect

The key will be immediately disabled and cannot be restored. Any systems using this key will lose access.

---

Rate Limits

API requests are limited based on your subscription tier:

Subscription	Requests per Minute	Burst Limit
Small Business	100	150
Medium Business	500	750
Enterprise	2,000	3,000

📊 Rate Limit Headers

Each API response includes rate limit headers:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 1640000000

Header	Description
X-RateLimit-Limit	Your tier's limit per minute
X-RateLimit-Remaining	Requests remaining in window
X-RateLimit-Reset	Unix timestamp when limit resets

Exceeded Limits?

If you exceed your rate limit, requests return HTTP 429. Contact support if you need higher limits.

---

Authentication Methods

🔑 Header Auth

API Key in Header (Recommended)

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.castellanai.com/v1/events

🔗 Query Parameter

API Key in Query (Not Recommended)

Security Risk

Query parameters may be logged in server access logs. Use header authentication instead.

curl "https://api.castellanai.com/v1/events?api_key=YOUR_API_KEY"

---

Getting Help

Customer Type	Support Channel
Enterprise	Dedicated Technical Account Manager
All Customers	support@castellanai.com

For detailed technical API documentation, contact support to request access to the Developer Portal.

---

What's Next?

Guide	Description
Data Export	Export security data to external systems
Webhooks	Receive real-time event notifications
Integrations	Pre-built integrations