API Authentication
The Cloudgeni API uses API keys for authentication. This guide covers how to create, manage, and use API keys to access the API securely.
Overview
All API requests require authentication via the X-CLOUDGENI-API-KEY header:
curl -H "X-CLOUDGENI-API-KEY: your-api-key" \
https://api.cloudgeni.ai/api/v1/organizations
Important: Use the X-CLOUDGENI-API-KEY header, not Authorization or x-api-key.
Creating API Keys
Step 1: Navigate to API Keys
- Log in to your Cloudgeni dashboard
- Go to Settings → API Keys
- Click Create API Key
| Field | Description |
|---|
| Name | Descriptive name (e.g., “CI/CD Pipeline”, “Local Development”) |
| Expiration | Optional expiration date |
| Scopes | Permissions for the key (see Scopes section) |
Step 3: Save the Key
Copy your API key immediately. It won’t be shown again after creation.
Using API Keys
Include the API key in every request:
curl -X GET \
-H "X-CLOUDGENI-API-KEY: cg_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
https://api.cloudgeni.ai/api/v1/organizations
Environment Variable
Set as environment variable for CLI tools:
export CLOUDGENI_API_KEY="cg_live_xxxxxxxxxxxxxxxxxxxx"
# Then use in commands
cloudgeni scan --api-key $CLOUDGENI_API_KEY
Code Examples
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.cloudgeni.ai/api/v1',
headers: {
'X-CLOUDGENI-API-KEY': process.env.CLOUDGENI_API_KEY,
'Content-Type': 'application/json'
}
});
// Make requests
const response = await client.get('/organizations');
Scopes and Permissions
API keys can have different permission levels:
Read-Only
Access to read data without modification:
- View organizations and members
- List repositories and scans
- Read findings and compliance data
- View integration status
Read-Write
Full access for automation:
- All read permissions
- Trigger scans
- Create remediations
- Update finding status
Admin
Full administrative access:
- All read-write permissions
- Manage API keys
- Configure integrations
- Manage organization settings
Rate Limits
API requests are rate limited to ensure fair usage:
| Tier | Requests per Minute | Burst |
|---|
| Free | 60 | 10 |
| Pro | 300 | 50 |
| Enterprise | 1000 | 100 |
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1640000000
Handling Rate Limits
When rate limited, you’ll receive a 429 Too Many Requests response:
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 60 seconds.",
"retry_after": 60
}
- Implement exponential backoff
- Cache responses where possible
- Use webhooks instead of polling
async function requestWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get("Retry-After") || 60;
await new Promise((r) => setTimeout(r, retryAfter * 1000));
continue;
}
return response;
}
throw new Error("Max retries exceeded");
}
Key Prefixes
API keys have prefixes to identify their type:
| Prefix | Type | Environment |
|---|
cg_live_ | Production | Live data |
cg_test_ | Test | Sandbox data |
Key Management
Listing Keys
View all API keys in Settings → API Keys:
- Key name and creation date
- Last used timestamp
- Expiration status
- Scope/permissions
Rotating Keys
To rotate a key:
- Create a new API key
- Update your applications to use the new key
- Verify the new key works
- Delete the old key
Schedule key rotation every 90 days for security best practices.
Revoking Keys
To immediately revoke a key:
- Go to Settings → API Keys
- Find the key to revoke
- Click Delete
- Confirm deletion
Revoked keys are immediately invalid for all API requests.
Security Best Practices
Never Commit Keys
Never commit API keys to version control.
# .env (add to .gitignore)
CLOUDGENI_API_KEY=cg_live_xxxxxxxxxxxxxxxxxxxx
Use Minimum Permissions
Create keys with only the permissions needed:
- CI/CD: Read-write for scanning
- Dashboards: Read-only for viewing
- Automation: Specific scopes only
Set Expiration
Configure expiration for temporary access:
- Short-lived for contractors
- Longer for production systems
- Review and rotate regularly
Monitor Usage
Track API key usage:
- Review last used timestamps
- Monitor for unexpected activity
- Set up alerts for suspicious patterns
Secure Storage
Use secret management services:
- AWS Secrets Manager
- Azure Key Vault
- HashiCorp Vault
- GitHub/GitLab secrets
Error Responses
Authentication Errors
401 Unauthorized - Invalid or missing API key:
{
"error": "unauthorized",
"message": "Invalid API key provided"
}
{
"error": "forbidden",
"message": "API key does not have permission for this action"
}
Troubleshooting
| Error | Cause | Solution |
|---|
| Invalid API key | Key doesn’t exist or was revoked | Create new key |
| Key expired | Expiration date passed | Create new key |
| Insufficient permissions | Key scope too limited | Create key with proper scope |
| Wrong header name | Using Authorization instead of X-CLOUDGENI-API-KEY | Use correct header |
