Skip to main content

​
Authentication

Lucitra Validate uses API keys for programmatic access and Stytch B2B session tokens for dashboard users. This page covers how authentication works, rate limits, enterprise tier gating, and debugging tools.

​
API Keys

API keys are the primary authentication method for the REST API, CLI, and MCP server. Generate keys from your dashboard at validate.lucitra.ai under Settings > API Keys. All API keys use the luci_ prefix and are passed as Bearer tokens in the Authorization header: 
curl https://api.lucitra.io/v1/datasets \
  -H "Authorization: Bearer luci_your_api_key"
API keys grant full access to your organization’s data. Never commit keys to version control, embed them in client-side code, or share them in plaintext. Use environment variables or a secrets manager.

​
Key Management

  • Keys can be created and revoked from the dashboard at any time
  • Each key is scoped to a single organization
  • Revoking a key takes effect immediately — all in-flight requests using that key will be rejected
  • There is no way to retrieve a key after creation; store it securely when generated

​
Rate Limiting

All API keys are subject to rate limits to ensure platform stability.
ParameterValue
Window60-second sliding window
Limit100 requests per window
ScopePer API key
When you exceed the rate limit, the API returns a 429 Too Many Requests response: 
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}
The response includes a Retry-After header with the number of seconds to wait. Implement exponential backoff in production clients rather than retrying immediately.
Rate limit headers are included on every response:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets

​
JWT Sessions (Dashboard)

The Lucitra Validate dashboard uses Stytch B2B session tokens for user authentication. These are managed automatically by the web application and are not required for API-only usage.
If you are only using the REST API, CLI, or MCP server, you do not need to interact with JWT sessions. API keys are sufficient for all programmatic access.
Dashboard sessions use short-lived JWTs issued by Stytch, with automatic refresh. Session tokens are scoped to the authenticated user’s organization and respect role-based access controls configured in the dashboard.

​
Enterprise Tier Gating

Certain endpoints are restricted to organizations on the Enterprise tier. Attempting to access these endpoints on a free or standard plan returns a 403 Forbidden response with the ENTERPRISE_REQUIRED error code. Gated capabilities include:
CapabilityEndpoints
Compliance engine/v1/compliance/*
Audit trail/v1/audit/*
Provenance tracking/v1/provenance/*
Model cards/v1/model-cards/*
Certification reports/v1/certifications/*
{
  "error": {
    "code": "ENTERPRISE_REQUIRED",
    "message": "This endpoint requires an Enterprise tier subscription.",
    "upgrade_url": "https://validate.lucitra.ai/settings/billing"
  }
}
Contact sales@lucitra.ai or visit your billing settings to upgrade to Enterprise.

​
Request IDs

Every API response includes an X-Request-Id header containing a unique identifier for that request. Include this ID when contacting support or filing bug reports. 
X-Request-Id: req_7f3a2b1c4d5e6f
Log X-Request-Id values in your application. When debugging issues, the Lucitra support team can trace the full request lifecycle using this identifier.

​
Extracting the Request ID

curl -v https://api.lucitra.io/v1/datasets \
  -H "Authorization: Bearer luci_your_api_key" 2>&1 | grep X-Request-Id

​
Security Best Practices

Rotate Keys Regularly

Generate new API keys periodically and revoke old ones. This limits the blast radius if a key is compromised.

Use Environment Variables

Store keys in environment variables or a secrets manager. Never hardcode keys in source files.

Monitor Usage

Review API usage in the dashboard to detect unexpected spikes that may indicate a leaked key.

Scope Access

Use separate API keys for different environments (development, staging, production) and services.