import { Tabs, Callout, Steps } from "nextra/components"; # TickTick The TickTick auth provider enables tools and agents to call [TickTick APIs](https://developer.ticktick.com/docs) on behalf of a user using OAuth 2.0 authentication. Want to quickly get started with TickTick in your agent or AI app? The pre-built [Arcade TickTick API MCP Server](/resources/integrations/productivity/ticktick-api) is what you want! ### What's documented here This page describes how to use and configure TickTick auth with Arcade. This auth provider is used by: - The [Arcade TickTick API MCP Server](/resources/integrations/productivity/ticktick-api), which provides pre-built tools for interacting with TickTick - Your [app code](#using-ticktick-auth-in-app-code) that needs to call the TickTick API - Or, your [custom tools](#using-ticktick-auth-in-custom-tools) that need to call the TickTick API ## Configuring TickTick auth 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. In a production environment, you will most likely want to use your own TickTick app credentials. This way, your users will see your application's name requesting permission. Before showing how to configure your TickTick app credentials, let's go through the steps to create a TickTick app. ### Create a TickTick app To integrate with TickTick's API, you'll need to set up OAuth 2.0 authentication by creating an app in the TickTick Developer Portal: #### Access the TickTick Developer Portal Navigate to the [TickTick Developer Portal](https://developer.ticktick.com/manage) and sign in with your existing TickTick credentials or create a new account. #### Create a new app 1. Once logged in, click on "New App" 2. Fill in the required details: - **App Name**: Choose a descriptive name for your application - **App Description**: Provide a brief description of your application's purpose - **App Icon**: Upload an icon to represent your application (optional) #### Configure OAuth settings 1. After creating your app, you'll receive a `Client ID` and `Client Secret` 2. Set the **Redirect URI** to the redirect URL generated by Arcade (see configuration section below) 3. Configure the required scopes for your application: - `tasks:read` - Read access to tasks - `tasks:write` - Write access to tasks (create, update, delete) - Add other scopes as needed for your use case For detailed instructions, refer to TickTick's official [API Documentation](https://developer.ticktick.com/docs). Next, add the TickTick app to Arcade. ## Configuring your own TickTick Auth Provider in Arcade ### Configure TickTick Auth Using the Arcade Dashboard GUI #### 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-ticktick"). - Optionally enter a **Description**. - Enter the **Client ID** and **Client Secret** from your TickTick app. - Configure the OAuth 2.0 endpoints: - **Authorization URL**: `https://ticktick.com/oauth/authorize` - **Token URL**: `https://ticktick.com/oauth/token` - Note the **Redirect URL** generated by Arcade. This must be set as your TickTick app's redirect URI. #### Create the provider Hit the **Create** button and the provider will be ready to be used. ### Configure TickTick Auth Using Configuration File This method is only available when you are [self-hosting the engine](/guides/deployment-hosting/on-prem #### Set environment variables Set the following environment variables: ```bash export TICKTICK_CLIENT_ID="" export TICKTICK_CLIENT_SECRET="" ``` Or, you can set these values in a `.env` file: ```bash TICKTICK_CLIENT_ID="" TICKTICK_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-ticktick description: TickTick OAuth 2.0 provider enabled: true type: oauth2 client_id: ${env:TICKTICK_CLIENT_ID} client_secret: ${env:TICKTICK_CLIENT_SECRET} oauth2: scope_delimiter: " " authorize_request: endpoint: "https://ticktick.com/oauth/authorize" params: response_type: code client_id: "{{client_id}}" redirect_uri: "{{redirect_uri}}" scope: "{{scopes}}" state: "{{state}}" token_request: endpoint: "https://ticktick.com/oauth/token" auth_method: client_secret_post params: grant_type: authorization_code client_id: "{{client_id}}" client_secret: "{{client_secret}}" code: "{{code}}" redirect_uri: "{{redirect_uri}}" response_content_type: application/x-www-form-urlencoded refresh_request: endpoint: "https://ticktick.com/oauth/token" auth_method: client_secret_post params: grant_type: refresh_token client_id: "{{client_id}}" client_secret: "{{client_secret}}" refresh_token: "{{refresh_token}}" response_content_type: application/x-www-form-urlencoded ``` When you use tools that require TickTick auth using your Arcade account credentials, Arcade will automatically use this TickTick OAuth provider. If you have multiple TickTick providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information. ## Using TickTick auth in app code Use the TickTick auth provider in your own agents and AI apps to get a user token for the TickTick 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 TickTick API: ```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-ticktick", scopes=["tasks:read", "tasks:write"] ) 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... ``` ```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-ticktick", [ "tasks:read", "tasks:write", ]); 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 TickTick auth in custom tools You can use the pre-built [Arcade TickTick API MCP Server](/resources/integrations/productivity/ticktick-api) to quickly build agents and AI apps that interact with TickTick. If the pre-built tools in the TickTick 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 TickTick API. Use the `OAuth2()` auth class to specify that a tool requires authorization with TickTick. The `context.authorization.token` field will be automatically populated with the user's TickTick 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-ticktick", scopes=["tasks:read"] ) ) async def get_ticktick_projects( context: ToolContext, ) -> Annotated[dict, "The list of projects."]: """ Retrieve all projects from TickTick. """ url = "https://api.ticktick.com/open/v1/project" headers = { "Authorization": f"Bearer {context.authorization.token}", } async with httpx.AsyncClient() as client: response = await client.get(url, headers=headers) response.raise_for_status() return dict(response.json()) ``` ## Available Scopes TickTick supports the following OAuth scopes that determine the level of access your application has: - `tasks:read` - Read access to tasks, projects, and related data - `tasks:write` - Full access to create, update, and delete tasks and projects For a complete list of available API endpoints and their required scopes, refer to the [TickTick API documentation](https://developer.ticktick.com/docs). ## API Endpoints TickTick provides a comprehensive REST API for managing tasks and projects. The base URL for all API requests is: ``` https://api.ticktick.com/open/v1 ``` Common endpoints include: - `/project` - Manage projects - `/task` - Manage tasks - `/user` - Get user information All API requests must include the OAuth access token in the `Authorization` header: ``` Authorization: Bearer {access_token} ``` For detailed API documentation, including request/response formats and examples, visit the [TickTick API Reference](https://developer.ticktick.com/docs).