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_
.
Tip
When testing the ClickUp API in your web browser, you can use a mock server which accepts any value in the Authorization header. Or you can use your own ClickUp account by generating a personal token.
Generate your personal API token
Any ClickUp user, including guests, can generate a personal token.
- Log into ClickUp.
- 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.
- Under API Token, click Generate.
- 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.
- Log into ClickUp.
- 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.
- Under API Token, click Regenerate.
- 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.
Note
ClickUp uses the authorization code grant type. OAuth tokens are not supported when using the Try It feature of this website.
Step 1: Create an OAuth app
Only the Workspace Owner or admins can access the Integrations page to create OAuth apps.
- Log into ClickUp.
- Click on your avatar in the lower-left corner and select Integrations.
- Click on ClickUp API.
- Click Create an App.
- Give your app a name and provide a redirect URL.
-
Once your app is created, you'll be provided with a
client_id
and asecret
.
Tip
Once a user is successfully authorized, they'll be redirected back to your app to start using it to access ClickUp API endpoints.
The redirect URL is the URL in your app where users need to go after authorizing ClickUp.
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}
Note
The protocol will default to https if not provided, and non-ssl redirect uris may not be supported in the future.
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?