Getting Your API Key

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 lupitor.acrely.ai and access to at least one company.

Step 1: Navigate to API Keys Page

Log in to your Lupitor dashboard at lupitor.acrely.ai
Select your company from the company dropdown in the top navigation bar
Click on “API Keys” in the main navigation menu

The URL will look like: https://lupitor.acrely.ai/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:

Read Only

Best for:

Analytics dashboards
Reporting tools
Read-only integrations

Can access:

List leads
View conversations
Get campaign data

Read + Write

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:

Copy to Clipboard - Click the copy icon (📋) to copy the key
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:

Copy the key to your password manager or environment variables
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

Environment Variables (Recommended)

Store your API key as an environment variable:

.env

LUPITOR_API_KEY=acr_1a2b3c4d5e6f7g8h9i0j...

Then access it in your code:

const apiKey = process.env.LUPITOR_API_KEY;

Secret Management Tools

Use a dedicated secret management service:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
1Password (for team secrets)

Password Managers

Store in your password manager:

1Password
LastPass
Bitwarden
Dashlane

❌ Never Do This

Never commit API keys to version control!

// ❌ 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:

.env
.env.local
.env.*.local

Step 5: Test Your API Key

Verify your API key works with a simple test request:

curl https://lupitor.acrely.ai/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID \
  -H "x-api-key: acr_1a2b3c4d5e6f7g8h9i0j..."

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:

Click the trash icon (🗑️) next to the key in the Actions column
Confirm the revocation in the dialog
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

Create New Key

Generate a new API key with the same permissions

Update Applications

Deploy the new key to all systems using the old key

Verify Migration

Check logs to confirm old key is no longer being used

Revoke Old Key

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

✅ Principle of Least Privilege

Only grant the minimum permissions needed

Use Read Only for dashboards
Scope to specific campaigns when possible
Create separate keys per use case

❌ Over-Privileged Keys

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:

Usage Monitoring

Check “Last Used” timestamps regularly
Look for keys that haven’t been used in 30+ days
Review request logs for unusual patterns

Alert on Anomalies

Unexpected IP addresses
Sudden spike in requests
Failed authentication attempts
Errors from previously stable integrations

Unused Key Cleanup

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

# ✅ 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:

Key was revoked (check status in dashboard)
Key was copied incorrectly (missing characters or prefix)
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:

Using a Read Only key for write operations
Campaign-scoped key accessing different campaign
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 for detailed information.

Next Steps

Now that you have your API key set up:

Quickstart Guide

Make your first API call in under 5 minutes

API Reference

Explore all available endpoints

Rate Limits

Understand rate limiting and best practices

Error Handling

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 for details
Contact support: Email us at info@acrely.ai
Check status: Visit status.lupitor.acrely.ai

Getting Started

Resources

Getting Your API Key

Overview

Step 1: Navigate to API Keys Page

Step 2: Create a New API Key

Key Name

Permissions (Scope)

Read Only

Read + Write

Campaign Scope (Optional)

Step 3: Save Your API Key

Save Options

Step 4: Store Your Key Securely

✅ Secure Storage Methods

❌ Never Do This

Step 5: Test Your API Key

Managing Your API Keys

Viewing Existing Keys

Monitoring API Usage

Revoking Keys

After Revocation

Security Best Practices

1. Rotate Keys Regularly

2. Use Different Keys Per Environment

3. Limit Permissions

✅ Principle of Least Privilege

❌ Over-Privileged Keys

4. Monitor and Alert

Troubleshooting

”Missing API key” Error

”Invalid or inactive API key” Error

”Insufficient permissions” Error

Rate Limit Exceeded

Next Steps

Quickstart Guide

API Reference

Rate Limits

Error Handling

Need Help?

Getting Started

Resources

​Overview

​Step 1: Navigate to API Keys Page

​Step 2: Create a New API Key

​Key Name

​Permissions (Scope)

Read Only

Read + Write

​Campaign Scope (Optional)

​Step 3: Save Your API Key

​Save Options

​Step 4: Store Your Key Securely

​✅ Secure Storage Methods

​❌ Never Do This

​Step 5: Test Your API Key

​Managing Your API Keys

​Viewing Existing Keys

​Monitoring API Usage

​Revoking Keys

​After Revocation

​Security Best Practices

​1. Rotate Keys Regularly

​2. Use Different Keys Per Environment

​3. Limit Permissions

✅ Principle of Least Privilege

❌ Over-Privileged Keys

​4. Monitor and Alert

​Troubleshooting

​”Missing API key” Error

​”Invalid or inactive API key” Error

​”Insufficient permissions” Error

​Rate Limit Exceeded

​Next Steps

Quickstart Guide

API Reference

Rate Limits

Error Handling

​Need Help?

Overview

Step 1: Navigate to API Keys Page

Step 2: Create a New API Key

Key Name

Permissions (Scope)

Campaign Scope (Optional)

Step 3: Save Your API Key

Save Options

Step 4: Store Your Key Securely

✅ Secure Storage Methods

❌ Never Do This

Step 5: Test Your API Key

Managing Your API Keys

Viewing Existing Keys

Monitoring API Usage

Revoking Keys

After Revocation

Security Best Practices

1. Rotate Keys Regularly

2. Use Different Keys Per Environment

3. Limit Permissions

4. Monitor and Alert

Troubleshooting

”Missing API key” Error

”Invalid or inactive API key” Error

”Insufficient permissions” Error

Rate Limit Exceeded

Next Steps

Need Help?