API Keys

API keys provide secure access to Crane Ledger's REST API. Each API key is organization-scoped and includes configurable permissions, usage tracking, and automatic rotation capabilities. API keys are the primary authentication method for programmatic access to your accounting data.

Authentication

API Key Header

All API requests require authentication using the Authorization header with your API key:

Authorization: Bearer cl_test_xxxxxxxxxxxxxxxxxxxxxxxx

Key Format

• Test Keys: Start with cl_test_ (for development and testing)
• Live Keys: Start with cl_live_ (for production use)
• Length: 32-character secure random strings

Security Features

• Organization Scoping: Keys only access data within their organization
• Permission Controls: Configurable access levels per key
• Usage Tracking: Automatic monitoring of API calls and costs
• Expiration: Optional automatic key expiration
• Rotation: Secure key replacement without service interruption

The API Key Object

{
  "id": "key_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Production API Key",
  "description": "Main API key for production application",
  "key_preview": "cl_live_xxxx...xxxx",
  "permissions": {
    "accounts": ["read", "write"],
    "transactions": ["read", "write"],
    "reports": ["read"],
    "api_keys": ["read"]
  },
  "status": "Active",
  "expires_at": "2025-01-15T00:00:00Z",
  "last_used_at": "2024-01-10T14:30:00Z",
  "usage_this_month": 1250,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:00:00Z"
}

Attributes

List API Keys

Returns a list of API keys for the organization. Actual API keys are never returned in full - only masked previews are shown.

Path Parameters

Query Parameters

Response

{
  "object": "list",
  "data": [
    {
      "id": "key_xxxxxxxxxxxxxxxx",
      "name": "Production API Key",
      "key_preview": "cl_live_xxxx...xxxx",
      "status": "Active",
      "last_used_at": "2024-01-10T14:30:00Z",
      "usage_this_month": 1250,
      "created_at": "2024-01-01T10:00:00Z"
    },
    {
      "id": "key_yyyyyyyyyyyyyyyy",
      "name": "Development API Key",
      "key_preview": "cl_test_xxxx...xxxx",
      "status": "Active",
      "last_used_at": "2024-01-09T09:15:00Z",
      "usage_this_month": 45,
      "created_at": "2023-12-15T16:20:00Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}

Create API Key

Creates a new API key for the organization. The full API key is returned only once during creation - store it securely as it cannot be retrieved later.

Path Parameters

Request Body

Permissions Structure

{
  "permissions": {
    "accounts": ["read", "write"],
    "transactions": ["read"],
    "reports": ["read", "write"],
    "api_keys": ["read"],
    "organizations": ["read"]
  }
}

Available permissions:

• read: View/list resources
• write: Create/update resources
• delete: Delete resources

Response

{
  "id": "key_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Mobile App API Key",
  "description": "API key for mobile application",
  "api_key": "cl_test_abcdefghijklmnopqrstuvwxyz012345",
  "permissions": {
    "accounts": ["read"],
    "transactions": ["read", "write"],
    "reports": ["read"]
  },
  "status": "Active",
  "expires_at": "2025-01-15T00:00:00Z",
  "created_at": "2024-01-10T14:30:00Z",
  "updated_at": "2024-01-10T14:30:00Z"
}

Get API Key

Retrieves the details of a specific API key. The full API key value is never returned - only a masked preview.

Path Parameters

Response

{
  "id": "key_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Mobile App API Key",
  "description": "API key for mobile application",
  "key_preview": "cl_test_xxxx...xxxx",
  "permissions": {
    "accounts": ["read"],
    "transactions": ["read", "write"],
    "reports": ["read"]
  },
  "status": "Active",
  "expires_at": "2025-01-15T00:00:00Z",
  "last_used_at": "2024-01-10T14:30:00Z",
  "usage_this_month": 45,
  "created_at": "2024-01-10T14:30:00Z",
  "updated_at": "2024-01-10T14:30:00Z"
}

Update API Key

Updates an existing API key's metadata, permissions, or expiration.

Path Parameters

Request Body

Response

{
  "id": "key_xxxxxxxxxxxxxxxx",
  "name": "Updated Mobile App Key",
  "description": "Updated permissions for mobile app",
  "permissions": {
    "accounts": ["read", "write"],
    "transactions": ["read", "write"],
    "reports": ["read"],
    "invoices": ["read", "write"]
  },
  "updated_at": "2024-01-11T09:15:00Z"
}

Rotate API Key

Creates a new API key with the same permissions and settings, while keeping the old key temporarily active for a grace period. This allows for seamless key rotation without service interruption.

Path Parameters

Response

{
  "id": "key_yyyyyyyyyyyyyyyy",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Mobile App API Key (Rotated)",
  "api_key": "cl_test_newkeyabcdefghijklmnopqrstuvwxyz",
  "permissions": {
    "accounts": ["read", "write"],
    "transactions": ["read", "write"],
    "reports": ["read"],
    "invoices": ["read", "write"]
  },
  "status": "Active",
  "expires_at": "2025-01-15T00:00:00Z",
  "created_at": "2024-01-11T10:30:00Z",
  "rotated_from": "key_xxxxxxxxxxxxxxxx"
}

Revoke API Key

Immediately revokes an API key, preventing all future API calls using that key.

Path Parameters

Response

{
  "id": "key_xxxxxxxxxxxxxxxx",
  "status": "Revoked",
  "revoked_at": "2024-01-11T11:00:00Z"
}

API Key Best Practices

Key Management

• Environment Separation: Use separate keys for development, staging, and production
• Minimal Permissions: Grant only necessary permissions for each use case
• Regular Rotation: Rotate keys every 90-180 days or when team members change
• Naming Conventions: Use descriptive names indicating purpose and environment

Security Practices

• Secure Storage: Store keys in environment variables or secure vaults
• No Hardcoding: Never embed API keys in source code or client-side applications
• Access Control: Limit key access to authorized team members only
• Monitoring: Regularly review key usage and unusual activity

Permission Design

• Read-Only Keys: For reporting and analytics applications
• Write-Only Keys: For data import and transaction creation
• Admin Keys: Full access for management applications
• Scoped Keys: Limited to specific resources or operations

Usage Monitoring

• Rate Limiting: Monitor API call patterns to detect abuse
• Cost Tracking: Track credit usage per key for budgeting
• Audit Logs: Maintain logs of key usage for compliance
• Alerts: Set up notifications for unusual usage patterns

Common Patterns

• Service Accounts: Dedicated keys for automated systems
• User-Specific Keys: Individual keys for different users/applications
• Temporary Keys: Short-lived keys for testing or integrations
• Emergency Keys: Backup keys for incident response

• ✨ For LLMs/AI assistants: Read our structured API reference