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. This is done by redirecting them 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 |
|---|---|
| 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, andnone.
- 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.