Authentication

Crane Ledger supports two authentication methods for the REST API and MCP server:

1. OAuth 2.1 (recommended for Claude/ChatGPT custom connectors) — login flow with scoped access tokens
2. Static API keys (ha_live_ / ha_test_) — instant org-scoped keys for scripts and self-serve onboarding

Both methods use Authorization: Bearer <token> on every request.

Base URL

https://api.craneledger.ai

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

OAuth 2.1 (MCP Connectors)

Crane Ledger implements the MCP authorization spec with a self-hosted authorization server.

Scopes

Unauthenticated MCP requests return 401 with a WWW-Authenticate header pointing at the protected-resource metadata document.

Claude.ai custom connector

1. In Claude, add a custom connector with URL https://api.craneledger.ai/mcp
2. Claude discovers OAuth via WWW-Authenticate and registers via DCR
3. Complete the GitHub login + consent flow at https://craneledger.ai/oauth/consent
4. Select organization and approve scopes — tools load with org scope from your token

Static API keys continue to work unchanged alongside OAuth tokens.

API Keys

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Key Types

Key Management

You can create, manage, and rotate API keys through the API or Dashboard. Each key includes:

• Organization scoping: Keys only access data within their organization
• Granular permissions: Control what resources and operations each key can access
• Usage tracking: Monitor API calls and credit consumption
• Expiration dates: Optional automatic key expiration
• Rotation support: Secure key replacement without service interruption

For detailed information about API key management, see the API Keys documentation.

Making Authenticated Requests

Include your API key in the Authorization header with the Bearer prefix:

Organization Context

Crane Ledger is a multi-tenant platform where all resources belong to an organization. The organization ID is included in the URL path for all API endpoints:

https://api.craneledger.ai/organizations/{organization_id}/...

Organization IDs always start with org_ and are included in your API key's scope. You can find your organization ID in the Dashboard or through the API.

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Common authentication errors:

• invalid_api_key: The API key is malformed or doesn't exist
• expired_api_key: The API key has reached its expiration date
• insufficient_permissions: The API key lacks permission for the requested operation
• organization_not_found: The organization ID in the URL doesn't exist or isn't accessible

Rate Limiting and Credits

Crane Ledger uses a credit-based pricing system where each API call consumes credits. Your API key's usage is tracked in real-time.

Credit Costs

Rate Limits

• Per API Key: 1000 requests per hour
• Per Organization: 10000 requests per hour
• Burst Limit: 100 requests per minute

When you exceed rate limits, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Try again later.",
    "retry_after": 60,
    "status": 429
  }
}

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