TickTick

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

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, which provides pre-built tools for interacting with TickTick
• Your app code that needs to call the TickTick API
• Or, your custom tools that need to call the TickTick API

Configuring TickTick auth

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:

For detailed instructions, refer to TickTick’s official API Documentation .

Next, add the TickTick app to Arcade.

Configuring your own TickTick Auth Provider in Arcade

export TICKTICK_CLIENT_ID="<your client ID>"
export TICKTICK_CLIENT_SECRET="<your client secret>"

TICKTICK_CLIENT_ID="<your client ID>"
TICKTICK_CLIENT_SECRET="<your client secret>"

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 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 to understand how this works.

Use client.auth.start() to get a user token for the TickTick 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-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...

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 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 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:

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 .

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 .