Authentication

In order to use the ClickUp API, you'll need to authenticate every request.

If you're using the ClickUp API for personal use, you can use your personal API token.

If you're building an app or integration for other people to use, you can use our OAuth flow, which allows ClickUp users to authorize specific Workspaces for your app.

You must include the token in the Authorization header of your API requests.

Either way you choose to authenticate, you and your app's users will only have access and permission to the information they can access through ClickUp.

Personal token

If you are using the API for your own use, or for testing purposes, you can use a personal API token. Personal tokens will always begin with pk_.

Generate your personal API token

Any ClickUp user, including guests, can generate a personal token.

1. Log into ClickUp.
2. In ClickUp 2.0, click your avatar in the lower-left corner and select Apps. In ClickUp 3.0 , click your avatar in the upper-right corner, select Settings , and scroll down to click click Apps in the sidebar.
3. Under API Token, click Generate.
4. You can copy and paste your personal API token wherever you need it!

Regenerate a personal API token

You can regenerate your personal API token at any time. Your existing token will be revoked and will no longer have access to your ClickUp account.

1. Log into ClickUp.
2. In ClickUp 2.0, click your avatar in the lower-left corner and select Apps. In ClickUp 3.0 , click your avatar in the upper-right corner, select Settings , and scroll down to click click Apps in the sidebar.
3. Under API Token, click Regenerate.
4. Your new API token is available immediately!

OAuth flow

When you want to develop an application that others can use, you must go through the OAuth2 flow so that every user that uses your application gets assigned an individualized token. This way each user of your application is able to access their own ClickUp resources.

Step 1: Create an OAuth app

Only the Workspace Owner or admins can access the Integrations page to create OAuth apps.

1. Log into ClickUp.
2. Click on your avatar in the lower-left corner and select Integrations.
3. Click on ClickUp API.
4. Click Create an App.
5. Give your app a name and provide a redirect URL.
6. Once your app is created, you'll be provided with a client_id and a secret .

Step 2: Retrieve an Authorization code

When a user wants to connect your app with their ClickUp account, you’ll need to share this URL with the user: https://app.clickup.com/api?client_id={client_id}&redirect_uri={redirect_uri}

The redirect_uri must match the Redirect URL used when creating your app in ClickUp in step 1.

You can also include a state parameter, for example: https://app.clickup.com/api?client_id={client_id}&redirect_uri={redirect_uri}&state={state}

Once the user has accepted or rejected the authorization request, they will be redirected back to the redirect_uri with the necessary query parameters for getting an access token.

Select specific Workspaces

Users can select one or more Workspaces to authorize through the OAuth flow.

Below is a screenshot of what a user sees when they visit the Workspace prompts URL.

Get Workspaces You can use the Get Authorized Teams (Workspaces) endpoint to see which Workspaces each user has authorized for your app.

If they have not given you access to the appropriate Workspaces, you can redirect them to the authorization code URL from step 2 at any time to reauthorize your app, which allows the user to add or remove Workspaces.

Step 3: Request a token

Once you have retrieved the authorization code, you can then use the Get Access token endpoint with the parameters client_id, client_secret , and code to get a user access token.

This is the token that is used in the Authorization header for all API requests made by your app on behalf of the authorized user.

Want to learn more about OAuth?

• OAuth.net
• OAuth Simplified
• Digital Ocean Intro to OAuth 2.0