Authentication

The Crane Ledger REST API uses API keys to authenticate requests. All API requests require a valid API key in the Authorization header. API keys are organization-scoped and can have configurable permissions.

Base URL

https://api.craneledger.ai

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

API Key Header

Include your API key in every request using the Authorization header with the Bearer scheme:

Authorization: Bearer cl_test_xxxxxxxxxxxxxxxxxxxxxxxx

or for production:

Authorization: Bearer cl_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key Types

Key TypePrefixUse Case
Livecl_live_Production environment, real credit consumption
Testcl_test_Development and testing, mock credit consumption

Security

  • All requests must use HTTPS. Calls over plain HTTP will fail.
  • Never share API keys or commit them to version control.
  • Store keys in environment variables or a secure secret manager.
  • Use separate keys for development, staging, and production.

Making Authenticated Requests

Organization Context

Crane Ledger is multi-tenant. All resources belong to an organization, and the organization ID is part of the URL path:

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

Organization IDs start with org_. Your API key is scoped to one or more organizations. Use the organization ID that corresponds to the key when calling the API. You can find your organization ID in the Dashboard or via the API.

Key Management

You can create, list, update, and revoke API keys via the API or Dashboard. Each key can have:

  • Organization scoping – access only to that organization’s data
  • Granular permissions – read/write/delete per resource type
  • Usage tracking – API calls and credit consumption
  • Expiration – optional expiration date
  • Rotation – replace keys without downtime

For full API key CRUD and permission details, see API Keys in the API Reference.

Authentication Errors

Failed authentication returns 401 Unauthorized with a JSON error body:

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

Common error codes:

CodeDescription
invalid_api_keyAPI key is malformed or does not exist
expired_api_keyAPI key has passed its expiration date
insufficient_permissionsKey lacks permission for the requested operation
organization_not_foundOrganization ID in the URL does not exist or is not accessible

For more on error handling, see Errors.

Secure Key Storage

Store API keys in environment variables or a secure vault. Never embed them in client-side code or expose them in logs or URLs.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.