API keys

API keys

Read-only endpoints (/calendar, /calendars, /events, /easter) are publicly accessible without authentication. However, if you plan to make frequent requests, you should register as a developer and obtain an API key. Write endpoints (PUT/PATCH/DELETE on /data, /tests, /temporale) always require authentication.

Unauthenticated requests are rate-limited by IP address. Authenticated requests with an API key have their own per-key rate limit, which can be configured when the key is generated.

Registering as a developer

1. Create an account on the Liturgical Calendar website using the Zitadel OIDC login flow (sign up with email or a supported identity provider).

2. Request the developer role from your account profile. An administrator will review and approve the request.

3. Once approved, the Developer Dashboard becomes available in your account, where you can manage applications and API keys.

Creating an application

From the Developer Dashboard, create a new application by providing:

• Name (required) — a descriptive name for your application (max 100 characters)
• Description (optional) — what your application does (max 500 characters)
• Website (optional) — URL of your application or project
• Requested scope — read (default) or write

The application starts in a pending state and must be approved by an administrator before you can generate API keys. If an application is rejected, you can edit it and resubmit for review.

Generating an API key

Once your application is approved, you can generate one or more API keys from the Developer Dashboard. When generating a key, you can optionally specify:

• Name — a label to identify the key
• Scope — read or write (constrained by the application's requested scope)
• Rate limit — requests per hour (default: 100)
• Expiration date — when the key should expire (optional)

The plain-text API key is displayed only once at generation time. Store it securely — it cannot be retrieved later. Only a prefix (first 20 characters) is visible in the dashboard for identification.

API keys follow the format litcal_{environment}_{random} (e.g., litcal_prod_a1b2c3d4...).

Using an API key

Include the API key in your requests using the X-API-Key header:

curl -H "X-API-Key: litcal_prod_your-key-here" \
     https://litcal.johnromanodorazio.com/api/dev/calendar

Managing keys

From the Developer Dashboard you can:

• List all keys for an application
• Revoke a key (permanently deactivates it)
• Rotate a key (revokes the old key and generates a new one with the same settings)

---

For Developers: ← API Reference | Home | Examples →