> ## Documentation Index
> Fetch the complete documentation index at: https://lupitor-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Your API Key
> Step-by-step guide to creating and managing API keys
## Overview
This guide walks you through the complete process of creating, securing, and managing API keys for the Lupitor API. You'll need an API key to authenticate all API requests to our platform.
**Prerequisites**: You must have an account at [YOUR\_DEPLOYMENT.lupitor.com](https://YOUR_DEPLOYMENT.lupitor.com) and access to at least one company.
## Step 1: Navigate to API Keys Page
1. **Log in** to your Lupitor dashboard at [YOUR\_DEPLOYMENT.lupitor.com](https://YOUR_DEPLOYMENT.lupitor.com)
2. **Select your company** from the company dropdown in the top navigation bar
3. **Click on "API Keys"** in the main navigation menu
The URL will look like: `https://YOUR_DEPLOYMENT.lupitor.com/your-company-name/api-keys`
In this example, we're working with the "Goofy's" company. If you haven't created any API keys yet, you'll see an empty state with the message "No API keys yet" and a prompt to create your first key.
**About the Example Company**: Throughout this guide, we use "Goofy's" as our example company, which has a campaign called "Why does goofy goofy matter?" This is a demo campaign used for testing API key features.
## Step 2: Create a New API Key
On the API Keys page, click the **"Create API Key"** button in the top-right corner.
A dialog will appear with the following fields:
### Key Name
Give your API key a descriptive name that identifies its purpose.
**Examples:**
* `Production Key` (as shown in the screenshot)
* `CRM Integration`
* `Lead Upload System`
* `Analytics Dashboard`
Use clear, descriptive names so you can easily identify keys later when reviewing logs or revoking access.
### Permissions (Scope)
Choose the appropriate permission level:
**Best for:**
* Analytics dashboards
* Reporting tools
* Read-only integrations
**Can access:**
* List leads
* View conversations
* Get campaign data
**Best for:**
* CRM integrations
* Lead import systems
* Full-featured apps
**Can access:**
* All read operations
* Create/update leads
* Manage campaigns
Only grant **Write** permissions when necessary. Use **Read Only** for analytics and reporting tools.
### Campaign Scope (Optional)
Choose whether this key has company-wide access or is limited to a specific campaign:
* **All Campaigns** (default): Key can access data from any campaign in your company
* **Specific Campaign**: Key is restricted to a single campaign (e.g., "Why does goofy goofy matter?" campaign)
In the screenshot above, we've selected **"Read + Write"** permissions and **"All Campaigns"** for company-wide access. This gives the "Production Key" full access to all campaigns within the Goofy's company.
**When to scope to a campaign:**
* Sharing access with a third-party vendor who should only see one campaign
* Creating separate keys per use case for better security and monitoring
* Limiting blast radius if a key is compromised
* Testing integrations with a specific campaign before going company-wide
Once you've filled out the form, click **"Create Key"** to generate your API key.
## Step 3: Save Your API Key
After clicking **"Create Key"**, you'll see a success dialog showing your new API key.
**This is the ONLY time you'll see the full API key!** Once you close this dialog, the key cannot be retrieved again.
Notice the yellow warning banner that says **"Save this key securely"** - this emphasizes that you won't be able to see the full key again after closing this dialog.
### Save Options
You have two ways to save your key:
1. **Copy to Clipboard** - Click the copy icon (📋) to copy the key
2. **Download as File** - Click the download icon (⬇️) to save as a `.txt` file
In the screenshot, you can see the full API key starting with `acr_e1b019b405a70a56cce5e13837d5046e08b6d1eaa6a70b3b`. The key will be automatically named after your key name (e.g., `lead-upload-api-key.txt` for a key named "Lead Upload").
We recommend using both methods:
1. Copy the key to your password manager or environment variables
2. Download as backup and store in a secure location
After saving your key, click **"I've Saved My Key"** to close the dialog.
## Step 4: Store Your Key Securely
### ✅ Secure Storage Methods
Store your API key as an environment variable:
```bash .env theme={null}
LUPITOR_API_KEY=acr_1a2b3c4d5e6f7g8h9i0j...
```
Then access it in your code:
```javascript theme={null}
const apiKey = process.env.LUPITOR_API_KEY;
```
Use a dedicated secret management service:
* **AWS Secrets Manager**
* **HashiCorp Vault**
* **Azure Key Vault**
* **1Password** (for team secrets)
Store in your password manager:
* 1Password
* LastPass
* Bitwarden
* Dashlane
### ❌ Never Do This
**Never commit API keys to version control!**
```javascript theme={null}
// ❌ BAD - Never hardcode keys
const API_KEY = "acr_1a2b3c4d5e6f7g8h9i0j...";
// ✅ GOOD - Use environment variables
const API_KEY = process.env.LUPITOR_API_KEY;
```
Add `.env` to your `.gitignore`:
```gitignore theme={null}
.env
.env.local
.env.*.local
```
## Step 5: Test Your API Key
Verify your API key works with a simple test request:
```bash cURL theme={null}
curl https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID \
-H "x-api-key: acr_1a2b3c4d5e6f7g8h9i0j..."
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID',
{
headers: {
'x-api-key': process.env.LUPITOR_API_KEY
}
}
);
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import os
import requests
response = requests.get(
'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
params={'campaignId': 'YOUR_CAMPAIGN_ID'},
headers={'x-api-key': os.environ['LUPITOR_API_KEY']}
)
print(response.json())
```
If your request returns a `401 Unauthorized` error, double-check that:
* You copied the entire key (including the `acr_` prefix)
* The key hasn't been revoked
* You're including the `x-api-key` header
## Managing Your API Keys
### Viewing Existing Keys
On the API Keys page, you'll see a table with all your keys:
**Table Columns:**
* **Name**: The descriptive name you gave the key (e.g., "Lead Upload")
* **Key**: First 12 characters for identification (e.g., `acr_e1b019b4...`)
* **Scope**: Permission level (Read Only or Read + Write)
* **Campaign**: Campaign name or "All campaigns"
* **Status**: Active or Revoked
* **Created**: When the key was created (e.g., 10/29/2025)
* **Last Used**: Most recent API call using this key (or "Never" if unused)
In this example, you can see the "Lead Upload" key with Read + Write permissions for all campaigns, showing an Active status.
### Monitoring API Usage
Click the **"Request Logs"** tab to see all API requests made with your keys:
The Request Logs view shows comprehensive analytics:
**Summary Metrics:**
* **Total Requests**: 17 total API calls
* **Success Rate**: 76% of requests succeeded
* **Avg Response Time**: 113ms average response time
* **Error Count**: 4 failed requests (shown in red)
**Detailed Log Table:**
* **Time**: Exact timestamp of each request
* **API Key**: Which key was used (e.g., "Read Company-Wide", "Write Company-Wide")
* **Method**: HTTP method (GET, POST, etc.)
* **Endpoint**: API endpoint called (e.g., `/api/v1/leads`, `/api/v1/leads/bulk`)
* **Campaign**: Which campaign the request was for
* **Status**: HTTP status code (200 = success, 500/400 = error)
* **Response Time**: How long the request took (in milliseconds)
In this example from "API Test Company", you can see a mix of successful GET requests (200 status in green) and POST requests (201 status), along with one failed request (500 status in red).
Review logs regularly to:
* Monitor for unusual activity
* Debug integration issues (check failed requests)
* Track API performance (response times)
* Verify requests are succeeding
### Revoking Keys
If a key is compromised or no longer needed, revoke it immediately:
1. Click the **trash icon** (🗑️) next to the key in the Actions column
2. Confirm the revocation in the dialog
3. The key will be marked as **Revoked** and stop working immediately
The confirmation dialog warns you: **"Are you sure you want to revoke this API key? This action cannot be undone, and any applications using this key will immediately lose access."**
**Revoking a key is immediate and permanent.** Applications using this key will immediately lose access. Make sure to update any integrations before revoking.
#### After Revocation
Once revoked, keys are marked with a red "Revoked" badge in your API keys list. Here's what a list with multiple revoked keys looks like:
This example from "API Test Company" shows several revoked keys with different scopes:
* **Read Campaign-Scoped**: Read-only access to "Test Campaign" (Revoked)
* **Write Campaign-Scoped**: Read + Write access to "Test Campaign" (Revoked)
* **Read Company-Wide**: Read-only access to all campaigns (Revoked)
* **Write Company-Wide**: Read + Write access to all campaigns (Revoked)
* **Write Wrong Campaign**: Read + Write access to "Wrong Campaign" (Revoked, never used)
Notice how revoked keys still show their last used date, which helps you track when they were last active before revocation.
## Security Best Practices
### 1. Rotate Keys Regularly
Generate a new API key with the same permissions
Deploy the new key to all systems using the old key
Check logs to confirm old key is no longer being used
Once verified, revoke the old key
**Recommended rotation schedule:**
* Production keys: Every 90 days
* Development keys: Every 180 days
* Immediately after: Team member departure, suspected breach, or security incident
### 2. Use Different Keys Per Environment
Create separate API keys for each environment:
| Environment | Key Name | Scope |
| ----------- | --------------------- | --------- |
| Production | `Production CRM` | Write |
| Staging | `Staging Tests` | Write |
| Development | `Dev Environment` | Write |
| Analytics | `Analytics Dashboard` | Read Only |
This allows you to:
* Revoke a single environment without affecting others
* Monitor usage per environment
* Apply different security policies
### 3. Limit Permissions
Only grant the minimum permissions needed
* Use **Read Only** for dashboards
* Scope to specific campaigns when possible
* Create separate keys per use case
Avoid creating overly permissive keys
* Don't use **Write** when **Read** is enough
* Don't use company-wide when one campaign suffices
* Don't share keys across multiple apps
### 4. Monitor and Alert
Set up monitoring for your API keys:
* Check "Last Used" timestamps regularly
* Look for keys that haven't been used in 30+ days
* Review request logs for unusual patterns
* Unexpected IP addresses
* Sudden spike in requests
* Failed authentication attempts
* Errors from previously stable integrations
* Audit keys quarterly
* Revoke keys not used in 90+ days
* Document active keys and their purposes
## Troubleshooting
### "Missing API key" Error
**Problem:** API returns `401 Unauthorized` with "Missing API key"
**Solution:**
* Verify you're including the `x-api-key` header (lowercase)
* Check that the header value is not empty
* Ensure no extra whitespace around the key
```bash theme={null}
# ✅ Correct
x-api-key: acr_1a2b3c4d...
# ❌ Wrong header name
X-API-KEY: acr_1a2b3c4d...
# ❌ Wrong header name
api-key: acr_1a2b3c4d...
```
### "Invalid or inactive API key" Error
**Problem:** API returns `401 Unauthorized` with "Invalid or inactive API key"
**Possible Causes:**
1. Key was revoked (check status in dashboard)
2. Key was copied incorrectly (missing characters or prefix)
3. Using the displayed prefix instead of full key
**Solution:**
* Verify key status in dashboard (Active vs Revoked)
* If revoked, create a new key
* Ensure you copied the entire key including `acr_` prefix
* Try copying the key again from your secure storage
### "Insufficient permissions" Error
**Problem:** API returns `403 Forbidden` with "Insufficient permissions"
**Possible Causes:**
1. Using a **Read Only** key for write operations
2. Campaign-scoped key accessing different campaign
3. Attempting to access resources outside key's scope
**Solution:**
* Check key's scope in dashboard
* Create a new key with **Write** permissions if needed
* Verify the `campaignId` matches the key's scope
* Use a company-wide key if accessing multiple campaigns
### Rate Limit Exceeded
**Problem:** API returns `429 Too Many Requests`
**Limit:** 1,000 requests per hour per API key
**Solution:**
* Implement exponential backoff
* Check `X-RateLimit-Reset` header for reset time
* Consider batching requests (use bulk endpoints)
* Create separate keys for different systems
See [Rate Limits](/rate-limits) for detailed information.
## Next Steps
Now that you have your API key set up:
Make your first API call in under 5 minutes
Explore all available endpoints
Understand rate limiting and best practices
Learn how to handle API errors gracefully
## Need Help?
If you're having issues with API keys:
* **Check the logs**: Review request logs in the dashboard
* **Read the docs**: See [Authentication](/authentication) for details
* **Contact support**: Email us at [support@lupitor.com](mailto:support@lupitor.com)
* **Check status**: Visit [status.YOUR\_DEPLOYMENT.lupitor.com](https://status.lupitor.com)