Integration Summary
When to use- API key and JWT authentication for the Lev API.
- Use the read and write examples together so you can validate state before you mutate it.
Required scopes- Access is inherited from the connected user or JWT session.
- Inspect GET /me or the validate-api-key response to confirm the scopes available to the current token.
Headers- Authorization: Bearer <token>
- X-Origin-App: <client-name>
- Content-Type: application/json on write operations
Request schemaUse the path and query parameter tables below or /platform/openapi.json for the machine-readable schema surface.
Response schemaResponses use the standard request_id/timestamp/data envelope documented in the API overview.
Enums & values- Enum-like values and filter operators are documented inline on the page where available.
- When a value set is account- or tier-dependent, validate against live responses before hard-coding assumptions.
IdempotencyUse Idempotency-Key on retried writes when your client cannot guarantee whether a prior attempt succeeded.
Rate limitsSee /rate-limits. Page intentionally through list endpoints and apply backoff on 429 responses.
Examplescurl, TypeScript, Python
Starter example: POST /api/external/v2/auth/validate-api-key
bash
curl -X POST "https://api.levcapital.com/api/external/v2/auth/validate-api-key" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Origin-App: my-integration"Authentication
Last updated: March 2026
All API requests must be authenticated. The Lev API supports two authentication methods: API keys for server-to-server integrations and JWT tokens for interactive clients.
Overview
| Method | Use Case | Token Lifetime |
|---|---|---|
| API Key | Server-to-server, CI/CD, automation | Long-lived (until revoked) |
| JWT (Auth0) | Interactive clients, MCP servers | Short-lived (configurable) |
Both methods use the
Authorization: Bearer <token> header. The API determines the token type automatically.API Key Authentication
API keys are the simplest way to authenticate. Create a key via the API or the Lev platform, then include it in every request:
bash
curl -X GET "https://api.levcapital.com/api/external/v2/deals" \
-H "Authorization: Bearer lev_sk_abc123def456..." \
-H "X-Origin-App: my-integration"API keys are scoped to a specific user and account. The key inherits the user's permissions — a key cannot access resources the user doesn't have access to.
Key validation
You can validate a key programmatically to check its scopes and associated account:
POST
/api/external/v2/auth/validate-api-keyValidate an API key (unauthenticated endpoint)
json
{
"api_key": "lev_sk_abc123def456..."
}Returns
{ "valid": true, "user_id": ..., "account_id": ..., "scopes": [...], "tier": "..." } if valid, or { "valid": false } if invalid.JWT Authentication
For interactive applications (like MCP servers connecting via OAuth), the API accepts Auth0-issued JWT tokens:
bash
curl -X GET "https://api.levcapital.com/api/external/v2/deals" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
-H "X-Origin-App: claude-desktop"JWT tokens are obtained through the OAuth 2.1 + PKCE flow. The MCP server handles this automatically for MCP clients like Claude Desktop and Cursor.
Required Headers
Every request must include:
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api_key_or_jwt> |
X-Origin-App | Yes | Identifies the calling application (e.g., my-integration, claude-desktop) |
Content-Type | For POST/PATCH | application/json |
Idempotency-Key | Recommended for writes | UUID to prevent duplicate operations (24-hour expiry) |
Authentication Errors
| Status | Meaning |
|---|---|
401 Unauthorized | Missing, invalid, or expired token |
403 Forbidden | Valid token but insufficient permissions for this resource |
json
{
"request_id": "...",
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired authentication token"
}
}