itellicoAI Documentation

Overview

API keys provide programmatic access to the itellicoAI platform, allowing you to integrate agents into your applications, automate tasks, and build custom workflows.

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
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

How to Create

Navigate to API Keys

Go to Settings → API Keys in your account

Click Create API Key

Click the Create API Key button

Create API Key dialog with key name and expiration date fields

Enter a Label

Give your key a descriptive name:

“Production Server”
“Development Environment”
“CI/CD Pipeline”
“Mobile App - iOS”

Set Expiration (Optional)

Optionally set an expiration date for automatic key rotation

Copy the Key

⚠️ IMPORTANT: The full key is shown only once!Copy it immediately and store securely.

Store Securely

Save the key in:

Environment variables
Secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
Password manager

Never commit to git or share publicly!

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 Authorization header:

curl https://api.itellico.ai/v1/agents \
  -H "Authorization: Bearer sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

Account Context

API keys are scoped to their account. When you create a key in a parent account, it can access both the parent and all subaccounts. To access a specific account, include the account ID in the URL path:

# Access parent account
curl https://api.itellico.ai/v1/accounts/me/agents \
  -H "Authorization: Bearer sk-a1b2c3d4.xyz789..." \
  -H "Content-Type: application/json"

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

SDKs

Using our official SDKs:

from itellico import ItellicoAI

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

# List agents
agents = client.agents.list()

Store API keys in environment variables and never hardcode them in your source code.

Managing API Keys

Viewing Keys

The API Keys page shows:

Label: Your descriptive name
Partial Key: First few characters (e.g., sk-a1b2c3d4...)
Status: Active, Revoked, or Expired
Created: When the key was created
Last Used: When it was last used for an API request
Expires: Expiration 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 itself (create a new one instead)
The account it belongs to

Revoking Keys

To temporarily disable a key without deleting:

Go to Settings → API Keys
Find the key in the list
Click Revoke
The key is disabled immediately

Why revoke instead of delete?

Keeps the key in logs for auditing
Can reactivate if revoked by mistake
Preserves creation date and history

Reactivating Keys

To restore a revoked key:

Find the revoked key in the list
Click Reactivate
The key works immediately

Deleting Keys

To permanently remove a key:

Go to Settings → API Keys
Find the key in the list
Click the menu (⋯) → Delete
Confirm deletion

Deletion is permanent and cannot be undone. The key will immediately stop working.

Key Statuses

Status	Description	API Access
Active	Key is working normally	✅ Yes
Revoked	Manually disabled	❌ No
Expired	Past expiration date	❌ No

Best Practices

One Key Per Environment

Create separate keys for each environment:

Development: “Dev Server Key”
Staging: “Staging Environment”
Production: “Production Server”

Benefits:

Revoke dev keys without affecting production
Track usage by environment
Different expiration policies per environment

Use Environment Variables

Never hardcode API keys in your source code.Good:

import os
api_key = os.environ['ITELLICO_API_KEY']

Bad:

api_key = "sk-a1b2c3d4.xyz789..."  # DON'T DO THIS!

Environment files (.env):

ITELLICO_API_KEY=sk-a1b2c3d4.xyz789...

Add to .gitignore:

.env
.env.local
*.key

Regular Key Rotation

Rotate API keys periodically for security:Recommended schedule:

Production: Every 90 days
Staging: Every 180 days
Development: Yearly or when developers change

Rotation process:

Create new key with expiration date
Update applications with new key
Test thoroughly
Revoke old key
Delete old key after 30 days

Set Expiration Dates

Use expiration dates for:

Temporary access: Contractors, demos, POCs
Forced rotation: Production keys set to expire in 90 days
Time-limited features: Beta testing, trials

Example:

Create key on Jan 1
Set expiration to Apr 1 (90 days)
Get notified 7 days before expiration
Rotate key before expiration

Monitor Usage

Check “Last Used” timestamps regularly:

Never used: Delete unused keys
Old timestamp: Might be safe to revoke
Recent activity: Key is active

Review your API keys monthly to remove inactive ones.

Descriptive Labels

Use clear, descriptive key names:Good labels:

“Production API Server - us-east-1”
“Mobile App - iOS - Production”
“CI/CD - GitHub Actions”
“Webhook Handler - Staging”

Bad labels:

“API Key 1”
“Test”
“My Key”
“New Key”

Secrets Management

Use a secrets manager in production:Options:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager
1Password / LastPass (for teams)

Benefits:

Centralized secret storage
Automatic rotation
Audit logs
Access controls

Security Considerations

Never commit API keys to version control!If you accidentally commit a key:

Revoke the key immediately
Create a new key
Use git filter-branch or BFG Repo-Cleaner to remove from history
Force push to remote
Notify team members to pull latest

If a Key is Compromised

Revoke Immediately

Go to Settings → API Keys and revoke the compromised key

Create New Key

Generate a replacement key with a new label

Update Applications

Deploy the new key to all affected applications

Review Logs

Check usage logs for suspicious activity

Notify Team

Inform your team about the incident

Investigate

Determine how the key was compromised and prevent recurrence

Troubleshooting

401 Unauthorized

Causes:

Invalid API key
Revoked or expired key
Missing Authorization header
Incorrect header format

Solutions:

Verify the key is active in Settings
Check the header: Authorization: Bearer sk-...
Ensure no extra spaces or characters
Create a new key if lost

403 Forbidden

Causes:

Key doesn’t have access to the requested account
Requesting a subaccount the key can’t access
Account is inactive

Solutions:

Verify the key was created in the parent account or the subaccount you’re accessing
Check that the account ID in the URL is correct
Verify account status is active

429 Too Many Requests

Causes:

Exceeded rate limits
Too many concurrent requests

Solutions:

Implement exponential backoff
Cache responses when possible
Upgrade to higher tier plan
Spread requests over time

Key not working after creation

Possible causes:

Using wrong key (prefix vs full key)
Extra characters (newlines, spaces)
Revoked immediately after creation

Solutions:

Copy the full key including sk- prefix
Trim whitespace from stored key
Verify status is “Active”

FAQs

How many API keys can I create?

No hard limit, but we recommend:

Small teams: 3-5 keys
Medium teams: 10-15 keys
Enterprise: As needed per environment

Can I use one key across multiple accounts?

API keys created in a parent account can access both the parent and all its subaccounts. Keys created in a subaccount can only access that subaccount.

What happens if I delete a key?

API requests using that key will immediately fail with 401 Unauthorized. Update your applications first!

Can I see what a key was used for?

Yes. The “Last Used” timestamp shows when it was last accessed. For detailed logs, contact support about API access logs.

Do API keys expire automatically?

Only if you set an expiration date. Otherwise, keys remain active until revoked or deleted.

Can subaccounts have their own API keys?

Yes! Each subaccount can create independent API keys scoped to that subaccount’s context.

Next Steps

API Reference

Explore available API endpoints

SDKs

Use our official Python and TypeScript SDKs

Team Management

Manage team members

Get Started

Build

Test

Launch

Optimize

Accounts and Subaccounts

Partner Network

Legal

API Keys

Overview

What are API Keys?

Creating API Keys

How to Create

Using API Keys

Authentication Header

Account Context

SDKs

Managing API Keys

Viewing Keys

Editing Keys

Revoking Keys

Reactivating Keys

Deleting Keys

Key Statuses

Best Practices

Security Considerations

If a Key is Compromised

Troubleshooting

FAQs

Next Steps

API Reference

SDKs

Team Management

Get Started

Build

Test

Launch

Optimize

Accounts and Subaccounts

Partner Network

Legal

​Overview

​What are API Keys?

​Creating API Keys

​How to Create

​Using API Keys

​Authentication Header

​Account Context

​SDKs

​Managing API Keys

​Viewing Keys

​Editing Keys

​Revoking Keys

​Reactivating Keys

​Deleting Keys

​Key Statuses

​Best Practices

​Security Considerations

​If a Key is Compromised

​Troubleshooting

​FAQs

​Next Steps

API Reference

SDKs

Team Management

Overview

What are API Keys?

Creating API Keys

How to Create

Using API Keys

Authentication Header

Account Context

SDKs

Managing API Keys

Viewing Keys

Editing Keys

Revoking Keys

Reactivating Keys

Deleting Keys

Key Statuses

Best Practices

Security Considerations

If a Key is Compromised

Troubleshooting

FAQs

Next Steps