Manage Public ACLs with the ClickUp API

The ClickUp developer platform allows you to update Public Access Control Lists (ACLs) so you can fine-tune how your resources are shared and secured via the API. This how-to guide walks you step by step through using the PATCH /public/acl endpoint, based strictly on the official API reference.

Understanding ClickUp Public ACLs

Before sending any requests, it helps to understand what a Public ACL is in the ClickUp API. A Public ACL defines which actions are allowed for a specific public token on a given resource, such as a shared view or object.

At a high level, the PATCH /public/acl operation lets you:

• Modify what a public token can do with a resource.
• Change which object the token is associated with.
• Adjust metadata like optional names or labels.

The endpoint is available on the base URL provided by the ClickUp API and requires authentication via a personal token in the request header.

Prerequisites for Using the ClickUp Endpoint

Before you update a Public ACL, make sure you have everything ready:

• A valid ClickUp API token with the required scopes.
• The token value for the Public ACL you want to update.
• The object_id and object_type associated with the ACL.
• Access to the official reference at ClickUp Public ACL PATCH endpoint for up-to-date details.

If you need implementation support or broader API strategy help, you can also review consulting options at Consultevo.

ClickUp PATCH /public/acl Request Overview

The ClickUp API method to update a Public ACL uses the HTTP PATCH verb.

ClickUp endpoint and method

• Method: PATCH
• Path: /public/acl

This path does not include URL path parameters. Instead, all identifying data is provided in the JSON request body.

Required ClickUp headers

Include at least the following headers in your request:

• Authorization: Your ClickUp API token, usually in the format Authorization: <token>.
• Content-Type: application/json.

Without the correct authorization header, the ClickUp API will reject the request with an authentication error.

Build the ClickUp Public ACL Request Body

The body of the PATCH /public/acl request is a JSON object that identifies the Public ACL you are updating and provides new values for its properties.

Core identification properties

Use these properties to specify which ClickUp Public ACL should be updated:

• token (string): The public token associated with the ACL you want to change.
• object_id (string): The ID of the object the ACL applies to.
• object_type (string): The type of object, such as a particular shared resource type (the exact allowed values are defined in the API reference).

These fields ensure the ClickUp API knows precisely which ACL entry to patch.

Permission and configuration fields

In addition to identifiers, you can pass configuration fields that define what the public token can do. While the exact schema is defined in the official ClickUp documentation, typical fields include:

• Booleans that allow or deny certain actions.
• Optional descriptive fields like names or tags.
• Settings that control visibility or expiration rules, if defined for your object type.

You only need to include the fields you want to change. Unspecified properties remain as they are on the existing ACL.

Step-by-Step: Update a Public ACL in ClickUp

Follow these steps to send a successful PATCH /public/acl request using the ClickUp API.

Step 1: Collect ACL and object details

1. Locate the token for the Public ACL you intend to modify.
2. Identify the object_id linked to this token.
3. Confirm the correct object_type value from the ClickUp reference.

Having these details ready reduces validation errors when the request is processed.

Step 2: Prepare headers for the ClickUp call

1. Set Authorization to your personal or workspace ClickUp token.
2. Set Content-Type to application/json.
3. Include any additional headers recommended in the latest ClickUp API reference if applicable.

Ensure your token has sufficient permission to update Public ACLs for the selected resource.

Step 3: Create the JSON payload

Construct a JSON body that includes the identification fields and any fields you are updating. A generic structure looks like this:

{
  "token": "your-public-token",
  "object_id": "your-object-id",
  "object_type": "your-object-type",
  "some_permission_flag": true,
  "another_setting": "new-value"
}

The actual property names and accepted values must follow the schema documented on the ClickUp Public ACL reference page.

Step 4: Send the ClickUp PATCH request

Use your preferred HTTP client or API tool:

• Set method to PATCH.
• Set the path to /public/acl on the ClickUp API base URL.
• Add the headers and JSON body.
• Send the request and wait for the response.

The ClickUp service will validate your data and respond with the updated Public ACL or an error object.

Handle ClickUp API Responses and Errors

When the request succeeds, the response typically includes the updated ACL details. Use this to confirm that your changes were applied correctly.

Common success patterns

• HTTP status in the 2xx range.
• A JSON body echoing the Public ACL with new values.
• Confirmation of the same token, object_id, and object_type you sent.

Common ClickUp error scenarios

If something goes wrong, the ClickUp API returns an error status and message. Frequent issues include:

• 401 Unauthorized: Missing or invalid Authorization header.
• 403 Forbidden: The token lacks permission to change this ACL.
• 404 Not Found: The combination of token, object_id, and object_type does not match an existing Public ACL.
• 400 Bad Request: The JSON payload does not conform to the schema or required fields are missing.

When you receive an error, compare your request against the examples and schema shown in the official ClickUp documentation for this endpoint.

Best Practices for Secure ACL Updates in ClickUp

When you update Public ACLs with the ClickUp API, you are directly controlling who can access shared resources. Keep these practices in mind:

• Grant only the minimum permissions required for the public token.
• Use descriptive names or metadata to track why a token exists.
• Review existing Public ACLs regularly and revoke tokens you no longer need.
• Store your ClickUp API token securely and never embed it in client-side code.

Following these guidelines will help you maintain a secure and predictable configuration as you integrate with the ClickUp platform.

Where to Learn More About the ClickUp API

For exact field definitions, supported object types, and the most current examples, always refer to the official ClickUp Public ACL PATCH documentation. That page is the source of truth for schema, parameters, and any new capabilities added to this endpoint.

By combining that reference with this how-to guide, you can confidently automate updates to Public ACLs and align your application’s behavior with the sharing rules you define in ClickUp.