API Key Management

API keys allow you to access QuivaWorks programmatically for automation, integrations, and custom applications.

Creating an API Key

Navigate to API Keys

Click your profile icon in the bottom left → “Settings” → “API Keys”

Add New Key

Click the “Add” button

Name Your Key

Enter a descriptive name (e.g., “Production Integration”, “CI/CD Pipeline”, “Monitoring Script”)

Save Key Securely

Copy the API key immediately - it will only be shown once

You cannot view the API key again after closing the dialog. Store it securely in a password manager or secret management system immediately.

API Key Properties

User-Scoped

Keys are tied to the user who creates them and inherit that user’s permissions

3-Month Lifespan

All keys expire after 3 months for security

Revocable

Delete keys immediately if compromised

Managing API Keys

Viewing Your Keys

Navigate to Settings → API Keys
See a list of all your active keys showing:
- Key name
- Creation date
- Expiration date
- Last used date (if applicable)

Deleting an API Key

Navigate to Settings → API Keys
Click on the key name you want to delete
Click the “Delete” button
Confirm the deletion

Deleting a key immediately revokes access. Any applications using this key will stop working. Update applications with a new key before deleting the old one.

API Key Security Best Practices

Treat API keys like passwords. Never share them or expose them publicly.

Storage and Handling

Use Environment Variables

Do this:

# Store in environment variable
export QUIVA_API_KEY="your-api-key-here"

Never do this:

// Don't hardcode keys in your code
const apiKey = "ms_1234567890abcdef"; // BAD

Use Secret Management Systems

Store keys in secure secret management systems:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager
1Password/LastPass for Teams

These systems provide:

Encrypted storage
Access controls
Audit trails
Automatic rotation

Never Commit to Version Control

Add these patterns to your .gitignore:

.env
.env.local
.env.*.local
config/secrets.yml
**/api-keys.txt

Even in private repositories, avoid committing API keys. They can be exposed through:

Repository forks
Access changes
CI/CD logs
Backup systems

Limit Key Sharing

Key Rotation Strategy

Generate New Key

Create a new API key 2 weeks before the old one expires

Update Applications

Deploy the new key to all applications and services:

Update environment variables
Update secret management entries
Update CI/CD configurations

Test Thoroughly

Verify all integrations work with the new key:

Run automated tests
Check production traffic
Monitor error rates

Monitor Transition

Keep both keys active briefly to ensure smooth transition

Delete Old Key

Only after confirming the new key works everywhere and the old key is no longer in use

Set calendar reminders 2 weeks before key expiration to avoid service disruption. Consider automating rotation using your secret management system.

Organizing Multiple Keys

Separate Keys Per Environment

Create different keys for:

Production
Staging
Development/Testing
CI/CD pipelines
Third-party integrations

Use Descriptive Names

Clear naming helps track usage:

“Production API - Web App”
“GitHub Actions - Main Pipeline”
“Datadog Monitoring Integration”
“Staging Environment - QA Team”

Monitoring API Key Usage

Regularly audit your API keys to maintain security: Monthly Review Checklist:

List all active API keys in your account
Verify each key is still needed
Check last used dates for inactive keys
Delete keys that haven’t been used in 30+ days
Confirm key names accurately describe current usage

Watch for Unusual Patterns:

Unexpected spike in API calls
Calls from unfamiliar IP addresses or regions
Access outside normal business hours
Failed authentication attempts
Unusually large data transfers

While QuivaWorks doesn’t currently provide audit logs for API usage, we recommend implementing logging in your applications that use API keys to track their usage patterns.

If an API Key is Compromised

Act immediately if you suspect a key has been exposed or compromised.

Revoke Immediately

Navigate to Settings → API Keys
Click on the compromised key
Click “Delete”
Confirm deletion

Generate Replacement

Create a new API key with a different name immediately

Update Applications

Deploy the new key to all affected services as quickly as possible

Review Recent Activity

Check your application logs for any unauthorized or suspicious API usage

Assess Impact

Determine:

What resources were accessed
What data may have been exposed
What actions were performed
Duration of potential unauthorized access

Report if Needed

For serious breaches involving sensitive data, follow your incident response procedures

Common Ways Keys Get Exposed:

Accidentally committed to public GitHub repositories
Logged in plain text in application logs
Shared in Slack/email/chat messages
Included in error messages or stack traces
Stored in unencrypted configuration files
Exposed through compromised development machines

Using API Keys

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.quiva.ai/v1/agents

Common Integration Patterns

Node.js
Python
cURL

// Using environment variables
const apiKey = process.env.QUIVA_API_KEY;

const response = await fetch('https://api.quiva.ai/v1/agents', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

import os
import requests

# Load from environment
api_key = os.environ['QUIVA_API_KEY']

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.quiva.ai/v1/agents',
    headers=headers
)

# Load from environment variable
curl -H "Authorization: Bearer $QUIVA_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.quiva.ai/v1/agents

Error Responses

401 Unauthorized

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired"
}

Common Causes:

API key doesn’t exist
Key has been deleted
Key has expired (after 3 months)
Incorrect key format

Solution: Generate a new API key and update your application configuration.

403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "Your API key doesn't have access to this resource"
}

Common Causes:

User role lacks required permissions
Resource doesn’t exist
Resource belongs to different account
Operation not allowed for this role

Solution: Check the user’s role permissions or create a key from a user with appropriate access.

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later",
  "retry_after": 60
}

Common Causes:

Exceeded your plan’s rate limits
Too many concurrent requests
Burst limit exceeded

Solution: Implement exponential backoff and respect the retry_after header. Consider upgrading your plan for higher limits.

API Key Best Practices Checklist

Use this checklist when working with API keys:

Before Creating

Determine the specific purpose and required scope
Identify which user should own the key (inherits their permissions)
Choose a descriptive, meaningful name
Confirm you have a secure storage location ready

Upon Creation

Copy the key immediately to secure storage
Store in password manager or secret management system
Never commit to version control
Document where the key will be used
Set a calendar reminder for rotation (before 3-month expiration)

During Usage

Use environment variables, never hardcode
Implement proper error handling for API failures
Monitor usage and performance
Log API errors (but never log the key itself)
Use separate keys for different environments

Regular Maintenance

Review active keys monthly
Delete unused keys
Rotate keys before expiration
Audit API usage patterns
Update documentation when keys change
Test new keys before deleting old ones

Troubleshooting

API key not working after creation

Possible Issues:

Key not copied correctly (extra spaces, truncation)
Not included in Authorization header
Using wrong API endpoint
User permissions insufficient

Solutions:

Regenerate the key and copy carefully
Verify header format: Authorization: Bearer YOUR_KEY
Check API documentation for correct endpoints
Verify user role has required permissions

Key stopped working suddenly

Possible Issues:

Key expired (3-month lifespan)
Key was deleted by admin
User’s permissions changed
Account plan changed affecting limits

Solutions:

Check key expiration date
Verify key still exists in settings
Contact admin about permission changes
Generate new key and update applications

Getting rate limit errors

Possible Issues:

Exceeded your plan’s API rate limits
Too many concurrent requests
Application not handling retries properly

Solutions:

Implement exponential backoff
Reduce request frequency
Consider upgrading your plan
Batch requests where possible

Key accidentally exposed

Immediate Actions:

Delete the key immediately
Generate a new replacement key
Update all applications
Review recent API usage for unauthorized access
If in version control, contact support about repository history

Next Steps

API Reference

Complete API documentation and endpoints

Authentication

Secure your user account with MFA

Security Overview

Comprehensive security practices

Incident Response

What to do if compromised

Authentication Session Management

⌘I

Get Started

Flows

Agents

Account Management

Advanced

API Keys

API Key Management

Creating an API Key

API Key Properties

User-Scoped

3-Month Lifespan

Revocable

Managing API Keys

Viewing Your Keys

Deleting an API Key

API Key Security Best Practices

Storage and Handling

Key Rotation Strategy

Organizing Multiple Keys

Separate Keys Per Environment

Use Descriptive Names

Monitoring API Key Usage

If an API Key is Compromised

Using API Keys

Authentication

Common Integration Patterns

Error Responses

API Key Best Practices Checklist

Before Creating

Upon Creation

During Usage

Regular Maintenance

Troubleshooting

Next Steps

API Reference

Authentication

Security Overview

Incident Response

Get Started

Flows

Agents

Account Management

Advanced

​API Key Management

​Creating an API Key

​API Key Properties

User-Scoped

3-Month Lifespan

Revocable

​Managing API Keys

​Viewing Your Keys

​Deleting an API Key

​API Key Security Best Practices

​Storage and Handling

​Key Rotation Strategy

​Organizing Multiple Keys

Separate Keys Per Environment

Use Descriptive Names

​Monitoring API Key Usage

​If an API Key is Compromised

​Using API Keys

​Authentication

​Common Integration Patterns

​Error Responses

​API Key Best Practices Checklist

​Before Creating

​Upon Creation

​During Usage

​Regular Maintenance

​Troubleshooting

​Next Steps

API Reference

Authentication

Security Overview

Incident Response

API Key Management

Creating an API Key

API Key Properties

Managing API Keys

Viewing Your Keys

Deleting an API Key

API Key Security Best Practices

Storage and Handling

Key Rotation Strategy

Organizing Multiple Keys

Monitoring API Key Usage

If an API Key is Compromised

Using API Keys

Authentication

Common Integration Patterns

Error Responses

API Key Best Practices Checklist

Before Creating

Upon Creation

During Usage

Regular Maintenance

Troubleshooting

Next Steps