Authentication

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

Request Authentication

OneCal Unified uses API keys to authenticate requests to the Unified Calendar API. You can generate an API key in your OneCal Unified 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 OneCal Unified in the x-api-key header.

Example request with API key

curl https://api.onecalunified.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.

OAuth2 (Google & Microsoft)

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

Provider Type	Authentication URL
Google	GET /v1/oauth/authorize/{:APP_ID}/google
Microsoft	GET /v1/oauth/authorize/{:APP_ID}/microsoft

Once authenticated, OneCal Unified 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.

Name
prompt
Type
string
Description
The prompt to use for the OAuth2 flow. Possible values are consent, select_account, and none.
Name
loginHint
Type
enum
Description
The login hint to use for the OAuth2 flow. If you know which email address the user will need to authenticate with, you can provide it in this parameter.
Name
redirectUrl
Type
string
Description
The URL to redirect the end user to after authentication. This URL must be a valid redirect URL for the application in the OneCal Unified Dashboard under Configurations > Application.
Name
state
Type
string
Description
A string which will be passed back to you in the redirect URL. This can be used to store additional information about the user or request which you may need after the authentication is complete. We recommend using a base64 encoded string for this field.

Using the SDK

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

The getOAuthUrl function is only applicable to Google and Microsoft providers. For Apple Calendar, see Apple Calendar Authentication below.

TypeScript

import { getOAuthUrl } from '@onecal/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 OneCal Unified API.

The password must be an Apple app-specific password, not the user's regular iCloud sign-in password. See how to generate an Apple app-specific password for instructions. App-specific passwords require that two-factor authentication is enabled on the user's Apple ID.

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

You can also create or update Apple Calendar End User Accounts using the unified POST /v1/endUserAccounts endpoint with providerType set to APPLE and a password field.

POST/v1/basicAuth/connect/{APP_ID}/apple

Connect Apple Calendar

This endpoint authenticates an Apple Calendar account using Basic Auth and creates an End User Account.

Path parameters

Name
APP_ID
Type
string
Description
Your application ID from the OneCal Unified Dashboard.

Request body

Name
email
Type
string
Description
The user's Apple ID email address.
Name
password
Type
string
Description
An Apple app-specific password generated at appleid.apple.com.
Name
externalId
Type
string?
Description
An optional custom ID for the end user account.

Request

POST

/v1/basicAuth/connect/{APP_ID}/apple

curl -X POST https://api.onecalunified.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"}'

Response

{
  "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"
}