Docs: Google OAuth Setup

Creating a Google Calendar API Client and Obtaining OAuth Credentials

To build a client that interacts with the Google Calendar API and obtain your OAuth Client ID and Secret, follow these steps:

1. Set Up a Google Cloud Project

Go to the Google Cloud Console
Click on the project selector at the top, then choose New Project.
Enter a project name and click Create.

2. Enable the Google Calendar API

In the Cloud Console, search for “Google Calendar API” in the API Library.
Click on Google Calendar API and select Enable.

In the menu on the left, click APIs & Services > OAuth consent screen.
Set User Type (typically “External” for public apps).
Fill in required application information (Application name, logo, support email, domains).
Save and continue through the steps, adding any necessary scopes:
For full calendar access, use: https://www.googleapis.com/auth/calendar
You may also include more granular scopes if needed (e.g., readonly, calendar.events).

4. Understanding Scopes in Recal

Recal simplifies OAuth scope management by offering two easy-to-understand scope options that automatically map to the appropriate Google Calendar permissions:

Available Scopes

edit scope - Full calendar access

https://www.googleapis.com/auth/userinfo.email - User's email address
https://www.googleapis.com/auth/calendar - Full calendar access
https://www.googleapis.com/auth/calendar.events - Read/write event access

free-busy scope - Read-only access to availability

https://www.googleapis.com/auth/userinfo.email - User's email address
https://www.googleapis.com/auth/calendar.freebusy - Busy time information only

When you make API calls to Recal, the system automatically validates that users have the correct scopes for each operation. If a user's granted scopes are insufficient, the API returns a 403 Forbidden response with details about which scopes are needed.

For example, attempting to create an event requires write permissions. If the user only granted free-busy access, the API will return:

{
  "error": "Insufficient scopes for operation 'calendar.events.insert'. Required scope level: write. You need to request one of these scopes: ...",
  "operation": "calendar.events.insert",
  "validScopes": [
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/calendar.app.created",
    "https://www.googleapis.com/auth/calendar.events.owned"
  ],
  "data": null
}

You would then need to re-authenticate the user with the edit scope to grant the necessary permissions.

Best Practice

Only request the minimum scope level you need. Use free-busy for availability checking and edit when you need to create or modify events.

Upgrading Scopes: If you need to add more scopes to your application (e.g., upgrading from free-busy to edit), all existing users who authenticated with the previous scope level will need to re-authenticate. Their current OAuth connections will continue working but will only have access to the original scopes they granted. Plan scope requirements carefully before your initial launch to minimize user disruption.

5. Create OAuth Credentials (Client ID & Client Secret)

Go to APIs & Services > Credentials.
Click Create Credentials and choose OAuth client ID.
Select the appropriate Application Type:
For most web apps, choose Web application.
Enter a name for the credentials.
Under Authorized JavaScript origins, enter your app's domain.
Under Authorized redirect URIs, provide the URI to which Google will redirect users after authentication (e.g., https://yourapp.com/oauth2callback).
Click Create.
After creation, you will be presented with your Client ID and Client Secret. You can also download them as a JSON file. Store the secret securely—if lost, you'll need to generate a new one.

6. Add Client ID and Client Secret to Recal

Go to "OAuth Credentials" in the sidebar and add your Client ID and Client Secret as well as the redirect URL and hit save.

Google OAuth Setup