Skip to main content

​
API Key Management

API keys provide programmatic access to the itellicoAI platform, so you can integrate agents into your applications, automate tasks, and build custom workflows. They work alongside integrations to extend your agents’ capabilities.

​
What Are API Keys?

API keys are secure tokens that authenticate your API requests without requiring user login credentials. Key characteristics:
  • Account-scoped — Each key belongs to a specific account
  • Permission-aware — Requests still use the account and role permissions of the key owner
  • Secret — Treat like a password; never share or commit to version control
  • Revocable — Can be disabled or deleted at any time
  • Trackable — Monitor last used timestamp and activity

​
Creating API Keys

1

Navigate to API Keys

Go to Account → API Keys
2

Click Create API Key

Click the Create API Key button
3

Enter a Label

Give your key a descriptive name such as:
  • “Production Server”
  • “Development Environment”
  • “Automation System”
  • “Mobile App - iOS”
4

Set Expiration (Optional)

Optionally set an expiration date for automatic key rotation
5

Copy the Key

The full key is shown only once. Copy it immediately and store it securely.
The full API key is displayed only once at creation. If you lose it, you must create a new key.

​
Using API Keys

​
Authentication Header

Include your API key in the X-API-Key header: 
curl https://api.itellico.ai/v1/accounts/current \
  -H "X-API-Key: sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

​
Account Context

API keys are scoped to their account. Keys created in a parent account can access both the parent and all subaccounts. 
# Access parent account
curl https://api.itellico.ai/v1/accounts/me/agents \
  -H "X-API-Key: sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

# Access specific subaccount
curl https://api.itellico.ai/v1/accounts/{account-id}/agents \
  -H "X-API-Key: sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

​
SDKs

Using the official SDKs: 
from itellicoai import Itellicoai

client = Itellicoai(api_key="sk-a1b2c3d4.xyz789...")

# List agents
agents = client.agents.list("me")
Store API keys in environment variables and never hardcode them in your source code.

​
Managing API Keys

​
Viewing Keys

The API Keys page shows:
ColumnDescription
LabelYour descriptive name
Partial KeyFirst few characters for identification
StatusActive, Revoked, or Expired
CreatedWhen the key was created
Last UsedWhen it was last used for an API request
ExpiresExpiration date (if set)
The full key is never shown after creation — only the first few characters for identification.

​
Editing Keys

You can update:
  • Label — Change the descriptive name
  • Expiration date — Extend or set expiration
You cannot change the key string itself. Create a new key if needed.

​
Revoking Keys

To temporarily disable a key without deleting it:
  1. Go to Account → API Keys
  2. Find the key in the list
  3. Click Revoke
  4. The key is disabled immediately
Revoked keys can be reactivated later. This preserves audit history and creation metadata.

​
Deleting Keys

To permanently remove a key:
  1. Go to Account → API Keys
  2. Find the key and click the menu icon
  3. Select Delete
  4. Confirm deletion
Deletion is permanent and irreversible. The key immediately stops working.

​
Key Statuses

StatusDescriptionAPI Access
ActiveKey is working normallyYes
RevokedManually disabledNo
ExpiredPast expiration dateNo

​
Security Best Practices

If you accidentally commit a key:
  1. Revoke the key immediately
  2. Create a new key
  3. Ask your development team to remove the key from version control history.
  4. Deploy the new key to your applications
Never hardcode API keys in source code.
import os
api_key = os.environ['ITELLICOAI_API_KEY']
Add .env files to your .gitignore:
.env
.env.local
*.key
Create separate keys for development, staging, and production. This lets you revoke a compromised key without affecting other environments.
Recommended rotation schedule:
  • Production: every 90 days
  • Staging: every 180 days
  • Development: yearly or when team members change
Rotation process:
  1. Create a new key
  2. Update your application with the new key
  3. Test thoroughly
  4. Revoke the old key
  5. Delete the old key after 30 days
In production, store keys in a secrets manager:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Azure Key Vault
  • Google Secret Manager
  • 1Password or similar team solutions
Check “Last Used” timestamps regularly. Delete keys unused for more than 90 days.

​
If a Key Is Compromised

1

Revoke Immediately

Go to Account → API Keys and revoke the compromised key
2

Create a Replacement Key

Generate a new key in the same account with a descriptive label
3

Update Applications

Deploy the new key to all affected applications
4

Review Logs

Check usage logs for suspicious activity during the exposure window
5

Investigate

Determine how the key was compromised and take steps to prevent recurrence

​
Troubleshooting

Causes: Invalid key, revoked or expired key, missing or malformed X-API-Key header.Solutions: Verify the key is active in Settings. Check the header format: X-API-Key: sk-.... Ensure no extra spaces or characters.
Causes: The key owner does not have the required account permission, or the key cannot access the requested account.Solutions: Verify the account ID in the URL. Ensure the key was created in the correct account and that the creator still has the required role for the operation.
Causes: Rate limit exceeded.Solutions: Implement exponential backoff. Cache responses when possible. Spread requests over time.

​
FAQs

There is no hard limit. Keeping the number manageable is recommended — typically 3-5 keys for small teams, 10-15 for medium teams.
Keys created in a parent account can access the parent and all its subaccounts. Keys created in a subaccount can only access that subaccount.
Yes. Each subaccount can create independent API keys scoped to that subaccount.
Only if you set an expiration date at creation. Otherwise, keys remain active until revoked or deleted.

​
Next Steps

API Reference

Explore available API endpoints

SDKs

Use the official Python and TypeScript SDKs

Integrations

Connect third-party services and webhooks