API Keys

API keys are credentials that authenticate your requests to the Ayra API. Each key is a long string of random characters prefixed with an identifier indicating key type and environment.

Understanding API Keys

Keys look like this:

• • Live (Production) keys: sk_live_abc123xyz789...
• • Test (Sandbox) keys: sk_test_abc123xyz789...

The sk_ prefix stands for "secret key" - these keys should be kept confidential and never exposed publicly. The environment indicator (live or test) ensures you don't accidentally use production keys in development or vice versa.

Creating API Keys

Generate API keys through the Ayra dashboard in Settings > API Keys section.

Step-by-Step Key Creation:

1. 1. Navigate to Settings > API Keys in your Ayra dashboard
2. 2. Click "Create API Key" button
3. 3. Provide a descriptive name for the key (e.g., "Production Web App", "Dev Environment", "Mobile App")
4. 4. Select the environment: Live (Production) or Test (Sandbox)
5. 5. Choose permissions (scopes) for the key
6. 6. Optionally set an expiration date for enhanced security
7. 7. Click "Generate Key"

After copying, the dashboard shows only a truncated version:

sk_live_abc123...GHIJ

This truncation prevents casual viewing of the full key while allowing identification of which key is which.

API Key Naming Best Practices

Choose descriptive names that indicate the key's purpose:

Descriptive names help when you have multiple keys and need to identify which to revoke or rotate. They're especially important in team environments where multiple people manage keys.

API Key Permissions (Scopes)

API keys can be restricted to specific permissions controlling what operations they can perform. This principle of least privilege enhances security by ensuring keys have only necessary access.

Available Permission Scopes:

Creating Limited-Scope Keys:

Limited scopes reduce security risk. If a key with limited scope is compromised, attackers can only perform actions within that scope rather than having complete account access.

API Key Expiration

Set expiration dates on API keys for enhanced security. Expired keys automatically stop working, forcing key rotation and reducing the window of vulnerability if keys are compromised.

Expiration Best Practices:

Set calendar reminders before key expiration to generate replacement keys and update systems before the old key stops working.

Managing Multiple API Keys

As your usage grows, you'll likely have multiple API keys for different purposes. Effective management prevents confusion and security issues.

Key Organization Strategies:

Key Tracking:

Maintain a key registry documenting:

• • Key name and truncated identifier
• • Created date and expiration date
• • Purpose and usage location
• • Assigned owner or system
• • Permission scopes
• • Last rotation date

This registry helps during audits, troubleshooting, and security reviews.

Viewing and Managing Keys

The API Keys dashboard shows all your keys with relevant information:

Name: Production Web App
Key: sk_live_abc123...GHIJ
Environment: Live
Scopes: agents:read, agents:write, conversations:read
Created: Jan 15, 2025
Expires: Apr 15, 2025
Last Used: 2 hours ago
Status: Active

Available Actions:

• • View Details - See full key information (but not the complete key string)
• • Regenerate - Create a new key with same settings, revoking the old one
• • Edit - Change name, expiration, or scopes (creates new key, old one still works until revoked)
• • Revoke - Immediately disable the key, preventing all future use
• • View Usage - See API calls made with this key

Rotating API Keys

Regular key rotation is a security best practice. Rotation involves generating new keys and updating systems to use them before revoking old keys.

Rotation Process:

1. 1. Generate New Key - Create replacement key with same permissions and settings
2. 2. Update Systems - Deploy new key to all systems using the old key
3. 3. Verify - Confirm all systems are successfully using new key
4. 4. Monitor - Watch for any systems still using old key (shows in usage logs)
5. 5. Revoke Old Key - After confirming nothing uses it, revoke the old key

Rotation Timeline:

For zero-downtime rotation, both old and new keys should work simultaneously during transition:

• • Day 0: Generate new key
• • Days 1-7: Gradually update systems to use new key
• • Day 7: Verify all systems migrated
• • Day 8: Revoke old key

This gradual approach prevents service interruption if you miss updating some system.

Automated Rotation:

For mature operations, automate key rotation:

• • Script generates new key via API
• • Configuration management updates key in all systems
• • Automated testing verifies new key works
• • Old key is automatically revoked after grace period

Automation reduces human error and ensures rotation happens on schedule.

Revoking API Keys

Revoke keys when they're no longer needed, when you suspect compromise, when team members leave, or when rotating to new keys.

Revocation Reasons to Track:

• • Compromised (suspected security breach)
• • Replaced (part of normal rotation)
• • Unused (key created but never used)
• • Employee Departure (team member left)
• • Project Ended (integration no longer needed)

Tracking revocation reasons helps during security audits and post-incident reviews.

API Key Security Incidents

If you discover a key has been compromised:

Immediate Actions:

1. 1. Revoke the compromised key immediately
2. 2. Generate a replacement key
3. 3. Update systems that were using compromised key

Investigation:

1. 1. Review API logs for unauthorized activity
2. 2. Determine scope of compromise - what data was accessed?
3. 3. Identify how compromise occurred
4. 4. Assess impact to your systems and customers

Remediation:

1. 1. Address security weakness that led to compromise
2. 2. Rotate any other potentially compromised credentials
3. 3. Monitor for ongoing unauthorized activity
4. 4. Document incident and prevention measures

Notification:

1. 1. Notify affected customers if their data was compromised
2. 2. File required breach notifications if applicable
3. 3. Update security policies and training