Calendly

The Calendly auth provider enables tools and agents to call Calendly APIs  on behalf of a user using OAuth 2.0 authentication.

What’s documented here

This page describes how to use and configure Calendly auth with Arcade.

This auth provider is used by:

• The Arcade Calendly MCP Server, which provides pre-built tools for interacting with Calendly
• Your app code that needs to call the Calendly API
• Or, your custom tools that need to call the Calendly API

Configuring Calendly auth

In a production environment, you will most likely want to use your own Calendly app credentials. This way, your users will see your application’s name requesting permission.

Before showing how to configure your Calendly app credentials, let’s go through the steps to create a Calendly app.

Create a Calendly app

To integrate with Calendly’s API, you’ll need to create a developer account and register an OAuth application:

For detailed instructions, refer to Calendly’s Getting Started guide  and OAuth documentation .

Next, add the Calendly app to Arcade.

Configuring your own Calendly Auth Provider in Arcade

export CALENDLY_CLIENT_ID="<your client ID>"
export CALENDLY_CLIENT_SECRET="<your client secret>"

CALENDLY_CLIENT_ID="<your client ID>"
CALENDLY_CLIENT_SECRET="<your client secret>"

auth:
  providers:
    - id: arcade-calendly
      description: Calendly OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:CALENDLY_CLIENT_ID}
      client_secret: ${env:CALENDLY_CLIENT_SECRET}
      oauth2:
        authorize_request:
          endpoint: "https://auth.calendly.com/oauth/authorize"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            state: "{{state}}"
        token_request:
          endpoint: "https://auth.calendly.com/oauth/token"
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json

When you use tools that require Calendly auth using your Arcade account credentials, Arcade will automatically use this Calendly OAuth provider. If you have multiple Calendly providers, see using multiple auth providers of the same type for more information.

Using Calendly auth in app code

Use the Calendly auth provider in your own agents and AI apps to get a user token for the Calendly API. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for the Calendly API:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "{arcade_user_id}"
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="arcade-calendly"
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# Do something interesting with the token...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade();
 
const userId = "{arcade_user_id}";
 
// Start the authorization process
const authResponse = await client.auth.start(userId, "arcade-calendly");
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
const token = authResponse.context.token;
// Do something interesting with the token...

Using Calendly auth in custom tools

You can use the pre-built Arcade Calendly MCP Server to quickly build agents and AI apps that interact with Calendly.

If the pre-built tools in the Calendly MCP Server don’t meet your needs, you can author your own custom tools that interact with the Calendly API.

Use the OAuth2() auth class to specify that a tool requires authorization with Calendly. The context.authorization.token field will be automatically populated with the user’s Calendly token:

from typing import Annotated
 
import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2
 
 
@tool(
    requires_auth=OAuth2(provider_id="arcade-calendly")
)
async def get_user_info(
    context: ToolContext,
) -> Annotated[dict, "The user information."]:
    """
    Retrieve the authenticated user's information from Calendly.
    """
    url = "https://api.calendly.com/users/me"
    headers = {
        "Authorization": context.authorization.token,
    }
 
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return dict(response.json())

For more details about Calendly’s authentication, refer to the Calendly Authentication documentation .