Skip to main content

List API Keys

Retrieves all API keys for the authenticated user. By default, only active keys are returned.

Endpoint​

GET /api/v1/api-keys/

Authentication​

Requires JWT token (Bearer authentication).

Query Parameters​

ParameterTypeRequiredDefaultDescription
include_expiredbooleanNofalseInclude expired (inactive) keys in the response

Response​

Success Response (200 OK)​

{
  "api_keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "key_prefix": "sk_live_abc123",
      "description": "Production API key",
      "is_active": true,
      "last_used_at": "2024-01-20T14:30:00Z",
      "expires_at": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:30:00Z"
    },
    {
      "id": "660f9511-f3ac-52e5-b827-557766551111",
      "key_prefix": "sk_live_def456",
      "description": "Development testing",
      "is_active": true,
      "last_used_at": null,
      "expires_at": null,
      "created_at": "2024-01-10T09:15:00Z",
      "updated_at": "2024-01-10T09:15:00Z"
    }
  ],
  "total": 2
}

Response Fields​

FieldTypeDescription
api_keysarrayArray of API key objects
api_keys[].idUUIDUnique API key identifier
api_keys[].key_prefixstringFirst 14 characters (for identification)
api_keys[].descriptionstringKey description
api_keys[].is_activebooleanWhether key is active
api_keys[].last_used_atdatetimeWhen key was last used (null if never used)
api_keys[].expires_atdatetimeExpiration date (null if no expiration)
api_keys[].created_atdatetimeCreation timestamp
api_keys[].updated_atdatetimeLast update timestamp
totalintegerTotal number of keys returned
Full API Key Not Included

The full API key is never returned by this endpoint. Only the key_prefix is shown for identification purposes.

Examples​

# Get active keys only
curl https://api.callcov.com/api/v1/api-keys/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."


# Include expired keys
curl "https://api.callcov.com/api/v1/api-keys/?include_expired=true" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Use Cases​

Display API Keys in Dashboard​

async function loadAPIKeys() {
  const response = await fetch('https://api.callcov.com/api/v1/api-keys/', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  const { api_keys } = await response.json();

  // Render keys in UI
  const keysList = document.getElementById('api-keys-list');
  api_keys.forEach(key => {
    const keyElement = document.createElement('div');
    keyElement.className = 'api-key-item';
    keyElement.innerHTML = `
      <div class="key-prefix">${key.key_prefix}...</div>
      <div class="key-description">${key.description || 'No description'}</div>
      <div class="key-status">${key.is_active ? 'Active' : 'Expired'}</div>
      <button onclick="expireKey('${key.id}')">Revoke</button>
    `;
    keysList.appendChild(keyElement);
  });
}

Find Unused Keys​

def find_unused_keys(access_token):
    """Find API keys that have never been used"""
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(
        "https://api.callcov.com/api/v1/api-keys/",
        headers=headers
    )

    keys = response.json()['api_keys']
    unused_keys = [k for k in keys if k['last_used_at'] is None]

    print(f"Found {len(unused_keys)} unused keys:")
    for key in unused_keys:
        print(f"  - {key['key_prefix']} - {key['description']}")

    return unused_keys

Audit Key Usage​

from datetime import datetime, timedelta

def audit_key_usage(access_token):
    """Find keys not used in the last 30 days"""
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(
        "https://api.callcov.com/api/v1/api-keys/?include_expired=true",
        headers=headers
    )

    keys = response.json()['api_keys']
    thirty_days_ago = datetime.now() - timedelta(days=30)

    stale_keys = []
    for key in keys:
        if key['last_used_at']:
            last_used = datetime.fromisoformat(key['last_used_at'].replace('Z', '+00:00'))
            if last_used < thirty_days_ago:
                stale_keys.append(key)
        elif key['is_active']:
            # Active but never used
            created = datetime.fromisoformat(key['created_at'].replace('Z', '+00:00'))
            if created < thirty_days_ago:
                stale_keys.append(key)

    print(f"Found {len(stale_keys)} stale keys (unused for 30+ days):")
    for key in stale_keys:
        print(f"  - {key['key_prefix']} - {key['description']}")

    return stale_keys

Key Ordering​

Keys are returned in reverse chronological order (newest first) by creation date.

Limits​

There is no pagination for this endpoint. All keys (up to 10 active keys per user) are returned in a single response.

Errors​

401 Unauthorized​

Invalid or missing JWT token:

{
  "detail": "Could not validate credentials"
}

Security​

  • Full keys never exposed: Only the prefix is shown
  • User isolation: You can only see your own keys
  • Usage tracking: last_used_at helps identify active vs. dormant keys

Key Prefix Format​

The key_prefix field shows the first 14 characters of your API key:

sk_live_abc123...

This allows you to:

  • Identify which key is being used in logs
  • Match keys to their descriptions
  • Safely display keys in UI (prefix doesn't reveal full key)