LAPIS Authentication: API Key & OAuth 2.0 Methods (2026)

Authentication overview

LAPIS employs industry-standard authentication mechanisms to control access to its healthcare interoperability APIs, ensuring data security and regulatory compliance, particularly with HIPAA security rules. The choice of authentication method depends on the integration's architecture and the scope of access required. For server-to-server integrations where an application directly accesses LAPIS resources, API keys are the primary method. When a user's consent is required for an application to access their data on their behalf, OAuth 2.0 is utilized.

Both methods are designed to protect sensitive patient information and maintain the integrity of clinical workflows. LAPIS encourages developers to review the LAPIS security documentation for detailed information on their overall security posture and practices.

Supported authentication methods

LAPIS supports a range of authentication methods to accommodate different integration scenarios, prioritizing security and developer convenience. The primary methods available are API Key authentication and OAuth 2.0.

The following table outlines the supported methods and their typical use cases:

API Key Authentication

API keys are unique, secret tokens that identify your application to LAPIS. They are suitable for integrations where your application is the sole consumer of the API and doesn't require user delegation. When using API keys, they must be transmitted securely, often in the Authorization header as a Bearer token or a custom header, per LAPIS API reference documentation.

OAuth 2.0

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to a user's protected resources without exposing the user's credentials. LAPIS implements specific OAuth 2.0 grant types:

• Client Credentials Grant: Used by confidential clients to obtain an access token using only their client credentials (client ID and client secret). This is suitable for server-to-server communication where an application acts on its own behalf.
• Authorization Code Grant with PKCE (Proof Key for Code Exchange): Recommended for public clients (e.g., mobile apps, single-page web applications) to securely obtain access tokens. PKCE mitigates the risk of authorization code interception. This workflow involves redirecting the user to LAPIS for consent before an authorization code is exchanged for an access token.

For detailed implementation steps and endpoint specifics, consult the LAPIS developer's guide on authentication.

Getting your credentials

To access LAPIS APIs, you must first obtain the necessary authentication credentials. The process typically begins within the LAPIS Developer Dashboard or by contacting LAPIS support, depending on your account type and required access level.

For API Keys:

1. Sign up for a LAPIS account: If you don't have one, register on the LAPIS website.
2. Access the Developer Dashboard: Log in to your LAPIS account and navigate to the Developer Dashboard.
3. Generate an API Key: Look for a section related to "API Keys" or "Credentials." Follow the instructions to generate a new key. You may be prompted to name your key for organizational purposes and select its associated permissions or scopes.
4. Securely store your key: Once generated, LAPIS API keys are typically displayed only once. Copy it immediately and store it in a secure location, such as an environment variable or a secrets management service.

For OAuth 2.0 (Client ID and Client Secret):

1. Register your application: Within the LAPIS Developer Dashboard, locate the "Applications" or "OAuth Clients" section. Register a new application, providing details such as your application name, redirect URIs, and a brief description.
2. Receive Client ID and Client Secret: Upon successful registration, LAPIS will provide you with a unique Client ID and a Client Secret. The Client Secret, like an API key, should be treated as highly sensitive information and stored securely.
3. Configure Redirect URIs: Ensure that all redirect URIs used in your OAuth flow are correctly registered in your application settings on the LAPIS dashboard. This is crucial for the security of the Authorization Code Grant.

For sandbox access and testing, the LAPIS Developer Sandbox provides a controlled environment to generate credentials and experiment with API calls using non-production data.

Authenticated request example

Here's an example of how to make an authenticated request to a LAPIS API endpoint using an API key in the Authorization header. This example assumes you have obtained a LAPIS API key named YOUR_API_KEY.

Python Example:

import requests
import os

# It's best practice to store API keys in environment variables
api_key = os.environ.get("LAPIS_API_KEY")

if not api_key:
    print("Error: LAPIS_API_KEY environment variable not set.")
    exit()

base_url = "https://api.lapishealth.com/v1"
endpoint = "/patients" # Example endpoint
url = f"{base_url}{endpoint}"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    print("Successfully authenticated request.")
    print("Response status code:", response.status_code)
    print("Response data:", response.json())
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
except requests.exceptions.ConnectionError as err:
    print(f"Connection error occurred: {err}")
except requests.exceptions.Timeout as err:
    print(f"Timeout error occurred: {err}")
except requests.exceptions.RequestException as err:
    print(f"An unexpected error occurred: {err}")

Node.js Example:

import fetch from 'node-fetch';

// It's best practice to store API keys in environment variables
const apiKey = process.env.LAPIS_API_KEY;

if (!apiKey) {
    console.error("Error: LAPIS_API_KEY environment variable not set.");
    process.exit(1);
}

const baseUrl = "https://api.lapishealth.com/v1";
const endpoint = "/patients"; // Example endpoint
const url = `${baseUrl}${endpoint}`;

const headers = {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
};

async function makeAuthenticatedRequest() {
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: headers
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log("Successfully authenticated request.");
        console.log("Response status code:", response.status);
        console.log("Response data:", data);
    } catch (error) {
        console.error("An error occurred during the request:", error);
    }
}

makeAuthenticatedRequest();

These examples demonstrate including the API key in the Authorization header as a Bearer token, which is a common and secure practice for API key authentication. For more examples and details on specific endpoints, refer to the LAPIS API reference documentation.

Security best practices

Adhering to security best practices is essential when integrating with LAPIS, especially given the sensitive nature of healthcare data. Strong authentication practices protect both your application and patient privacy.

• Protect your API Keys and Client Secrets:
  • Environment Variables: Store API keys and client secrets as environment variables rather than hardcoding them directly into your application's source code. This prevents them from being exposed in version control systems.
  • Secrets Management: For production environments, utilize dedicated secrets management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) to securely store and retrieve credentials at runtime.
  • Never commit to VCS: Ensure your .gitignore file is configured to prevent accidental commits of files containing credentials.
• Limit API Key/Token Scopes:
  • When generating API keys or configuring OAuth clients, request only the minimum necessary permissions (scopes) required for your application's function. This principle of least privilege reduces the potential impact if a credential is compromised.
  • Regularly review and adjust permissions as your application's needs evolve.
• Secure Communication:
  • Always use HTTPS for all communication with LAPIS APIs. LAPIS enforces HTTPS to encrypt data in transit, protecting against eavesdropping and tampering.
• Error Handling and Logging:
  • Implement robust error handling for authentication failures. Avoid returning verbose error messages that might reveal sensitive information.
  • Log authentication attempts and failures, but ensure logs do not contain raw credentials or tokens. Monitor these logs for suspicious activity.
• Token Rotation and Expiration:
  • If LAPIS supports it, implement a strategy for regularly rotating API keys.
  • OAuth access tokens have a limited lifetime. Your application should be designed to gracefully handle token expiration and refresh tokens when necessary, minimizing service disruption.
• Validate Callbacks (OAuth 2.0):
  • For OAuth 2.0 implementations, always validate the state parameter in the callback from the authorization server to prevent CSRF attacks.
  • Ensure all registered redirect URIs are correct and secure.
• SDK Usage:
  • If available, leverage LAPIS SDKs (e.g., Python, Node.js) as they often handle authentication boilerplate and security best practices internally, reducing implementation errors.

By following these guidelines, developers can establish a secure and reliable integration with the LAPIS platform, safeguarding sensitive healthcare data.