Authentication

Generate a Luma API key from the dashboard and configure the @alhwyn/luma TypeScript SDK with the x-luma-api-key header for authenticated requests.

The SDK authenticates with the x-luma-api-key header on every request to https://public-api.luma.com.

Prerequisites

1. Luma Plus

   API access requires a Luma Plus organization. See the official getting started guide.

2. Create an API key

   Open Luma API keys and create a key for your calendar.

3. Store the key securely

   Never commit API keys to git. Use environment variables or a secrets manager.

Environment variables

Copy .env.example to .env in your project root:

cp .env.example .env

Set your key:

LUMA_API_KEY=your-key-here

Bun loads .env automatically. In Node.js, load it yourself or export the variable in your shell.

Initialize the client

import { Luma } from "@alhwyn/luma";

const luma = new Luma(process.env.LUMA_API_KEY!);

Pass the key as the first constructor argument. The SDK sends it on every outbound request.

Client options

const luma = new Luma(process.env.LUMA_API_KEY!, {
  baseUrl: "https://public-api.luma.com", // default
  fetch: customFetch, // optional, for testing or proxies
});

Use baseUrl only if you need to point at a different host (for example, a mock server in tests).

Verify your key works

Run a smoke test against the live API:

const user = await luma.users.get();
console.log(user.email);

See Test your setup for a full walkthrough.