Authentication

This page explains how to authenticate with the Lumea API to make secure requests.

Overview

The Lumea platform supports two authentication methods:

1. API Key Authentication - For programmatic access to the API
2. JWT Token Authentication - For user session management

All API endpoints are protected and require authentication using one of these methods.

Note: Each customer receives a custom deployment with a unique API endpoint. The examples in this documentation use generic endpoint paths that should be prefixed with your organization's specific API URL provided during onboarding.

API Key Authentication

API keys provide a simple way to authenticate API requests without handling user credentials.

Types of API Keys

The platform supports two types of API keys:

1. Master API Key - A system-wide API key with full access to all endpoints
2. Custom API Keys - User-created API keys with specific permissions

Getting an API Key

To obtain an API key:

1. Log in to your Lumea dashboard
2. Navigate to Settings > API Keys
3. Click Create New API Key
4. Give your key a descriptive name (e.g., "Production", "Development", "Testing")
5. Set appropriate permissions for the key
6. Click Generate Key

Once generated, make sure to copy and store your API key securely. For security reasons, we only show the complete key once.

Using API Keys

API keys can be provided in one of two ways:

1. HTTP Header (Recommended)

Include the API key in the x-api-key header:

x-api-key: your-api-key-here

Example request using curl:

curl -X GET "https://your-custom-endpoint.lumea.ai/workflows" \
  -H "x-api-key: your-api-key-here"

2. Query Parameter

Append the API key as a query parameter:

https://your-custom-endpoint.lumea.ai/workflows?api_key=your-api-key-here

API Key Security Best Practices

• Keep your API keys secure and don't expose them in client-side code
• Store API keys in environment variables for server applications
• Rotate API keys periodically for better security
• Use custom API keys with limited permissions whenever possible
• The master API key has full administrative access and should be used carefully

JWT Token Authentication

JWT (JSON Web Token) authentication is used for user sessions and provides a stateless authentication mechanism.

JWT Token Structure

JWT tokens consist of three parts:

• Header - Contains the token type and signing algorithm
• Payload - Contains claims about the user and token expiration
• Signature - Verifies the token hasn't been tampered with

Token Lifespan

By default, JWT access tokens are valid for 7 days. After this period, users need to obtain a new token by logging in again.

Using JWT Authentication

To authenticate with a JWT token, include it in the Authorization header with the Bearer prefix:

Authorization: Bearer your-jwt-token-here

Example request using curl:

curl -X GET "https://your-custom-endpoint.lumea.ai/workflows" \
  -H "Authorization: Bearer your-jwt-token-here"

JWT Security Considerations

• JWT tokens cannot be revoked before they expire
• Store JWT tokens securely on the client side
• The platform uses HTTPS to encrypt tokens during transmission

Administrative Access

Administrative access is determined by the user's role:

• Users with the admin role have administrative privileges
• The master API key automatically has administrative access

Rate Limiting

API requests are subject to rate limiting based on your plan. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Error Handling

If authentication fails, the API will respond with a 403 Forbidden error:

{
  "detail": "Invalid API Key or Session Token"
}

Security Best Practices

1. Use HTTPS for all API requests to ensure authentication credentials are encrypted
2. Don't hardcode API keys in client applications
3. Use environment variables to store API keys in server applications
4. Implement proper error handling for authentication failures
5. Use custom API keys with minimal required permissions when possible
6. For user-facing applications, prefer JWT tokens over API keys