import { Tabs, Callout, Steps } from "nextra/components";

# Calendly

The Calendly auth provider enables tools and agents to call [Calendly APIs](https://developer.calendly.com/api-docs) on behalf of a user using OAuth 2.0 authentication.

<Callout>
  Want to quickly get started with Calendly in your agent or AI app? The
  pre-built [Arcade Calendly MCP
  Server](/resources/integrations/productivity/calendly-api) is what you want!
</Callout>

### 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](/resources/integrations/productivity/calendly-api), which provides pre-built tools for interacting with Calendly
- Your [app code](#using-calendly-auth-in-app-code) that needs to call the Calendly API
- Or, your [custom tools](#using-calendly-auth-in-custom-tools) that need to call the Calendly API

## Configuring Calendly auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

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:

<Steps>

#### Create a Calendly developer account

1. Navigate to [developer.calendly.com/create-a-developer-account](https://developer.calendly.com/create-a-developer-account)
2. Sign up using your GitHub or Google account
3. Complete the registration process

#### Register a new OAuth application

1. Click on **Create New App** or **Register an App**
2. Fill in the required details:
   - **Application Name**: Choose a descriptive name for your application
   - **Type**: Select **Web** or **Native** based on your application type
   - **Environment**: Choose **Sandbox** (for testing) or **Production**
   - **Redirect URI**: Add the redirect URL generated by Arcade (see configuration section below)
     - For Sandbox: HTTP with localhost is allowed (e.g., `http://localhost:1234`)
     - For Production: HTTPS is required

#### Save your credentials

1. After registration, you'll receive your **Client ID**, **Client Secret**, and **Webhook Signing Key**
2. **Important**: Copy and save these credentials immediately, as the Client Secret and Webhook Signing Key won't be accessible again

</Steps>

For detailed instructions, refer to Calendly's [Getting Started guide](https://developer.calendly.com/getting-started) and [OAuth documentation](https://developer.calendly.com/api-docs/0b07b0a0b0b07-get-authorization-code).

Next, add the Calendly app to Arcade.

## Configuring your own Calendly Auth Provider in Arcade

<Tabs items={["Dashboard GUI", "Configuration File"]}>
<Tabs.Tab>

### Configure Calendly Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **OAuth 2.0** tab at the top.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "arcade-calendly").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Calendly app.
- Configure the OAuth 2.0 endpoints:
  - **Authorization URL**: `https://auth.calendly.com/oauth/authorize`
  - **Token URL**: `https://auth.calendly.com/oauth/token`
- Note the **Redirect URL** generated by Arcade. This must be set as your Calendly app's Redirect URI.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

</Tabs.Tab>

<Tabs.Tab>

### Configure Calendly Auth Using Configuration File

<Callout type="info">
  This method is only available when you are [self-hosting the
  engine](/guides/deployment-hosting/on-prem)
</Callout>

<Steps>

#### Set environment variables

Set the following environment variables:

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

Or, you can set these values in a `.env` file:

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

#### Edit the Engine configuration

Edit the `engine.yaml` file and add a new item to the `auth.providers` section:

```yaml
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
```

</Steps>

</Tabs.Tab>
</Tabs>

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](/references/auth-providers#using-multiple-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](/get-started/about-arcade) to understand how this works.

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

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {8-12}
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...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
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...
```

</Tabs.Tab>

</Tabs>

## Using Calendly auth in custom tools

You can use the pre-built [Arcade Calendly MCP Server](/resources/integrations/productivity/calendly-api) 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](/guides/create-tools/tool-basics/build-mcp-server) 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:

```python {8-12,22}
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](https://developer.calendly.com/how-to-guides/authentication).