Authentication

You'll need to authenticate your requests to access any of the endpoints in the Apiroc Calendar API. In this guide, we'll look at how authentication works.

Request Authentication

Apiroc uses API keys to authenticate requests to the Unified Calendar API. You can generate an API key in your Apiroc Dashboard, select your application and navigate to the API Keys page from the left navigation menu. Your API Key must then be passed to all requests made to Apiroc in the x-api-key header.

curl https://api.apiroc.com/api/v1/endUserAccounts \
  -H "x-api-key: {API KEY}"

End User Authentication

Your end users will need to authenticate their calendars with your application. For Google and Microsoft, this is done through an OAuth2 redirect flow. For Apple Calendar, authentication is done via a direct API call using the user's Apple ID email and an app-specific password. See Apple Calendar Authentication below. CalDAV accounts work the same way, plus the address of the user's CalDAV server. See CalDAV Authentication below.

OAuth2 (Google & Microsoft)

Redirect your end users to one of the URLs below for the provider they want to authenticate with. Apiroc will in-turn redirect the user to the OAuth2 flow for the specified provider based on the configurations you have made in the Apiroc Dashboard for that provider.

Once authenticated, Apiroc will redirect the end user back to your application with an endUserAccountId query parameter. You can then use the /v1/endUserAccounts endpoint to get the details of the end user account.

Query parameters

You can also pass additional query parameters to the authentication URL to control the behavior of the authentication flow.

Using the SDK

If you are using the SDK, you can get the OAuth authentication URL by doing the following:

import { getOAuthUrl } from '@apiroc/unified-calendar-api-node-sdk/oauth'

const googleUrl = getOAuthUrl('your-app-id', 'GOOGLE', {
  redirectUrl: 'https://your-app.com/callback',
  externalId: 'user-123',
  loginHint: 'user@example.com',
})

Apple Calendar Authentication

Apple Calendar uses a different authentication model. Instead of an OAuth2 redirect flow, your application collects the user's Apple ID email and an app-specific password, then sends them directly to the Apiroc API.

No redirect flow is involved — the End User Account is created and returned directly in the API response.

Connect Apple Calendar

curl -X POST https://api.apiroc.com/api/v1/basicAuth/connect/{APP_ID}/apple \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@icloud.com", "password": "xxxx-xxxx-xxxx-xxxx"}'

{
  "id": "user_account_1",
  "createdAt": "2025-09-12T10:15:00.000Z",
  "updatedAt": "2025-09-12T10:15:00.000Z",
  "email": "user@icloud.com",
  "externalId": "",
  "authorizedScopes": [],
  "providerAccountId": null,
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "APPLE"
}

CalDAV Authentication

CalDAV lets your users connect calendars from any standards-compliant CalDAV server, such as Fastmail, Yahoo, Zoho, GMX, mailbox.org or a self-hosted Nextcloud. Like Apple Calendar, there is no redirect flow: your application collects the server address, the user's login and an app-specific password, then sends them to the Apiroc API.

Apiroc discovers the user's calendars from the server address automatically (via /.well-known/caldav), so the base address of the server is usually enough.

Connect CalDAV

curl -X POST https://api.apiroc.com/api/v1/basicAuth/connect/{APP_ID}/caldav \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"serverUrl": "https://caldav.fastmail.com", "email": "user@fastmail.com", "password": "app-specific-password"}'

{
  "id": "user_account_2",
  "createdAt": "2026-10-08T10:15:00.000Z",
  "updatedAt": "2026-10-08T10:15:00.000Z",
  "email": "user@fastmail.com",
  "externalId": "",
  "authorizedScopes": [],
  "providerAccountId": null,
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "CALDAV",
  "serverUrl": "https://caldav.fastmail.com/"
}