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"

import requests

response = requests.get(
    "https://api.lucitra.io/v1/datasets",
    headers={"Authorization": "Bearer luci_your_api_key"},
)

const response = await fetch("https://api.lucitra.io/v1/datasets", {
  headers: {
    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.

Parameter	Value
Window	60-second sliding window
Limit	100 requests per window
Scope	Per 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:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix 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:

Capability	Endpoints
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

response = requests.get(
    "https://api.lucitra.io/v1/datasets",
    headers={"Authorization": "Bearer luci_your_api_key"},
)
request_id = response.headers.get("X-Request-Id")
print(f"Request ID: {request_id}")

const response = await fetch("https://api.lucitra.io/v1/datasets", {
  headers: { Authorization: "Bearer luci_your_api_key" },
});
const requestId = response.headers.get("X-Request-Id");
console.log(`Request ID: ${requestId}`);

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.

​Authentication

​API Keys

​Key Management

​Rate Limiting

​JWT Sessions (Dashboard)

​Enterprise Tier Gating

​Request IDs

​Extracting the Request ID

​Security Best Practices

Rotate Keys Regularly

Use Environment Variables

Monitor Usage

Scope Access

Authentication

API Keys

Key Management

Rate Limiting

JWT Sessions (Dashboard)

Enterprise Tier Gating

Request IDs

Extracting the Request ID

Security Best Practices