Skip to main content

API Key Management

The API Key Management interface provides a web-based UI for creating, monitoring, and managing API keys used for programmatic access to the OmniCRM API.

::: note ::: title Note :::

For general API authentication concepts and usage examples, see concepts_api. :::

Overview​

API keys enable secure, long-lived authentication for:

  • Server-to-server integrations
  • Automation scripts
  • Third-party applications
  • Scheduled tasks and cron jobs
  • External monitoring systems

Unlike JWT tokens (which expire after minutes/hours), API keys remain valid until manually revoked or until their expiry date.

Accessing API Key Management​

Navigate to:

Or directly:

Required Permission: MANAGE_API_KEYS (admin role)

API Key List View​

The main page displays all API keys in a table format:

Columns:

  • Name - Descriptive label for the API key (e.g., "Provisioning System", "Monitoring Tool")
  • Created By - Username of the person who created the key
  • API Key - The actual key string (partially masked for security)
  • Status - Active, Expired, or Revoked
  • Created Date - When the key was generated
  • Expiry Date - When the key will automatically expire
  • Actions - Edit, Delete, Regenerate buttons

Example Display:

Dashboard Widgets​

At the top of the page, summary statistics are displayed:

  • Total API Keys - Count of all API keys (active and inactive)
  • Active Keys - Currently valid keys
  • Expiring Soon - Keys expiring in the next 30 days
  • Expired Keys - Keys past their expiry date

Creating an API Key​

Step 1: Click "Add API Key"

Click the + Add button at the top right of the API Key list.

Step 2: Fill in Details

A modal form appears requesting:

Name: ________________________

: (e.g., "Provisioning System")

Description: __________________

: (Optional - purpose of this key)

Expiry Date: [Date Picker]

: (Optional - leave blank for no expiry)

Permissions: ☐ View Customers ☐ Create Customers ☐ View Services ☐ Create Services ☐ Provisioning ☐ View Inventory ☑ Admin (all permissions)

[Cancel] [Generate Key]

Field Guidelines:

Name (required)

  • Short, descriptive identifier
  • Examples: "Provisioning System", "Billing Integration", "Monitoring"
  • Used in audit logs and displayed in the list

Description (optional)

  • More detailed explanation
  • Examples: "Used by Ansible provisioning server", "Third-party billing sync"
  • Helps future administrators understand the key's purpose

Expiry Date (optional)

  • If blank: Key never expires (not recommended)
  • If set: Key automatically becomes invalid after this date
  • Recommended: Set expiry for security (90 days to 1 year)

Permissions

  • Select specific permissions or check "Admin" for full access
  • Follows same role-based permission model as user accounts
  • Best Practice: Assign minimum necessary permissions

Step 3: Generate and Copy Key

After clicking "Generate Key", the system displays the newly created API key:

⚠️ Copy this key now - it will not be shown again!

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[Copy to Clipboard]

[Close]

::: warning ::: title Warning :::

Save the API key immediately!

Once you close this dialog, the full key cannot be retrieved again. You'll only see a masked version (sk_live_...XYZ) in the list view.

If you lose the key, you must regenerate it, which invalidates the old key and may break existing integrations. :::

Step 4: Configure Your Application

Use the API key in your application's requests:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Or in environment variables:

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Managing Existing Keys​

Viewing Key Details​

Click on any API key name to view full details:

  • Full key name and description
  • Creation timestamp
  • Creator username
  • Associated permissions
  • Usage statistics (if implemented)
  • Recent access logs

Regenerating an API Key​

If an API key is compromised or lost, regenerate it:

  1. Click the ⋮ (three dots) in the Actions column
  2. Select "Regenerate Key"
  3. Confirm the action

::: warning ::: title Warning :::

Regenerating invalidates the old key immediately.

Any applications using the old key will stop working. Update all integrations with the new key before regenerating. :::

What Happens:

  • Old key is revoked
  • New key with same permissions is generated
  • New key is displayed (copy it immediately)
  • Name, description, and permissions remain unchanged

Revoking (Deleting) an API Key​

To permanently remove an API key:

  1. Click the ⋮ (three dots) in the Actions column
  2. Select "Delete"
  3. Confirm deletion

What Happens:

  • Key is immediately revoked
  • All requests using this key return 401 Unauthorized
  • Key is removed from the database
  • Cannot be undone - key cannot be recovered

When to Revoke:

  • Integration is no longer needed
  • Key has been compromised
  • System using the key has been decommissioned
  • Replacing with a new key with different permissions

Editing API Key Details​

To modify an API key's details:

  1. Click the ⋮ (three dots) in the Actions column
  2. Select "Edit"
  3. Update name, description, expiry, or permissions
  4. Click "Save Changes"

Editable Fields:

  • Name
  • Description
  • Expiry date
  • Permissions

Non-Editable:

  • The key value itself (use Regenerate to change)
  • Created date
  • Created by user

API Key Status​

API keys can have several statuses:

Active

  • Key is valid and can be used
  • Within expiry date (or no expiry set)
  • Not manually revoked
  • Displayed with green badge

Expiring Soon

  • Active but will expire in the next 30 days
  • Displayed with orange/warning badge
  • Consider rotating before expiry

Expired

  • Past the expiry date
  • No longer accepts authentication
  • Displayed with red badge
  • Can be deleted or expiry extended

Revoked

  • Manually deleted/disabled
  • Permanently invalid
  • No longer shown in active list

Filtering and Searching​

The API Key list supports:

Search:

Search by name, description, or partial key:

Filter by Status:

Filter dropdown to show:

  • All Keys
  • Active Only
  • Expiring Soon (next 30 days)
  • Expired

Sort:

Click column headers to sort by:

  • Name
  • Created Date
  • Expiry Date
  • Created By

Security Best Practices​

API Key Generation​

  • Length: Keys should be at least 32 characters (system enforces this)
  • Randomness: Generated using cryptographically secure random number generators
  • Format: Typically prefixed (e.g., sk_live_) for identification

API Key Storage​

In the CRM:

  • Keys are hashed before storage (like passwords)
  • Full key only shown once during creation
  • Database stores hash for verification
  • Even administrators cannot retrieve the full key later

In Your Application:

  • Store in environment variables, not code
  • Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
  • Never commit keys to version control
  • Rotate keys periodically (90-365 days)

Permission Management​

  • Principle of Least Privilege - Only grant necessary permissions
  • Avoid creating admin keys unless absolutely required
  • Use separate keys for different systems/purposes
  • Review permissions regularly

Monitoring and Auditing​

  • Monitor API key usage via activity logs
  • Set up alerts for unusual access patterns
  • Review "last used" timestamps regularly
  • Remove unused keys

Key Rotation​

Establish a key rotation policy:

  1. Create new key with same permissions
  2. Update applications to use new key
  3. Monitor to ensure old key is no longer used
  4. Revoke old key after grace period

Troubleshooting​

"401 Unauthorized" when using API key

  • Cause: Key invalid, expired, or incorrect
  • Fix:
    • Verify key is copied correctly (no extra spaces)
    • Check key status (Active vs. Expired)
    • Confirm key has required permissions
    • Ensure using X-API-KEY header (not Authorization)

"API key not found" after creation

  • Cause: Key may have been created but not properly stored
  • Fix:
    • Check API key list for the new entry
    • If missing, create a new key
    • Report issue to administrator

API key expiring soon

  • Cause: Expiry date approaching (within 30 days)
  • Fix:
    • Create new key with extended expiry
    • Update applications to use new key
    • Revoke old key after migration

Cannot delete API key

  • Cause: May be protected or in use
  • Fix:
    • Ensure you have admin permissions
    • Check if key is locked/protected
    • Contact administrator if issue persists

API Endpoints (for Programmatic Management)​

API keys can also be managed via API (requires admin permissions):

List API Keys

GET /crm/api-keys
Authorization: Bearer <admin-token>

Create API Key

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "New Integration",
  "description": "Third-party billing sync",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

Response:

{
  "api_key_id": 123,
  "name": "New Integration",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

Revoke API Key

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

Update API Key

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Updated Name",
  "expiry_date": "2026-12-31"
}

Common Use Cases​

Use Case 1: Provisioning System Integration

Create an API key for your Ansible provisioning server:

  1. Navigate to API Keys → Add
  2. Name: "Ansible Provisioning Server"
  3. Description: "Used by provisioning automation"
  4. Permissions: Provisioning, View/Create Services, View/Update Inventory
  5. Expiry: 1 year
  6. Copy key and add to Ansible crm_config.yaml

Use Case 2: Third-Party Billing Integration

Create a read-only key for billing export:

  1. Name: "Billing Sync - QuickBooks"
  2. Permissions: View Customers, View Transactions, View Invoices
  3. Expiry: 90 days (rotate quarterly)
  4. Use in scheduled export script

Use Case 3: Monitoring and Alerting

Create a key for Prometheus/Grafana metrics collection:

  1. Name: "Monitoring - Grafana"
  2. Permissions: View Services, View Provisioning
  3. Expiry: Never (monitoring needs continuous access)
  4. Configure in Grafana datasource

Use Case 4: Customer Portal API

Create a key for customer self-service portal:

  1. Name: "Customer Portal Backend"
  2. Permissions: View Own Customer, View Own Services, Create Payments
  3. Expiry: 180 days
  4. Use in portal backend API calls
  • concepts_api - API authentication concepts and examples
  • rbac - Role-based access control and permissions
  • 2fa - Two-factor authentication for additional security