---

name: clickup-install-auth description: >- Configure ClickUp personal-token or OAuth authorization with server-side storage, state validation, Workspace verification, and rotation ownership. Use when connecting an application to ClickUp. Trigger with "ClickUp auth", "install ClickUp API", or "ClickUp OAuth setup". argument-hint: "[repository-path] [personal|oauth]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.8.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• clickup
• authentication model: inherit effort: high compatibility: Designed for Claude Code; OAuth setup requires a ClickUp app owned by a Workspace owner or admin

---

ClickUp Authentication Setup

Overview

Choose the authentication mode by tenancy and ownership, then prove the authorized Workspace boundary without exposing credentials.

Prerequisites

• A server-side application boundary and governed secret manager
• For personal use/testing, an accountable ClickUp user; for public use, an owner/admin-created OAuth app
• Exact redirect URIs, state storage, and an expected Workspace allow-list

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.

Current Contract

• Personal tokens begin with pk_, are intended for individual/testing use, and do not expire unless regenerated or revoked.
• User-facing integrations use OAuth Authorization Code at https://app.clickup.com/api and exchange at https://api.clickup.com/api/v2/oauth/token.
• OAuth access tokens currently do not expire, but ClickUp marks that behavior subject to change.
• Every API request includes the token in Authorization; authorized Workspaces are verified through the teams endpoint.

Authentication

Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.

Instructions

1. Choose personal or OAuth mode and record credential owner, environment, and intended Workspaces.
2. Store token/client secret only in a secret manager and inject by reference at runtime.
3. For OAuth, register exact HTTPS redirects, generate/validate state, and exchange each code server-side once.
4. Call GET /api/v2/user and GET /api/v2/team with bounded timeouts.
5. Compare authorized Workspace IDs with the allow-list and reject cross-tenant ambiguity.
6. Document revocation/rotation, reauthorization, incident, and ownership-transfer procedures.

Approval Boundaries

Do not print tokens, put a client secret in frontend code, accept unvalidated state, silently expand Workspace authorization, or regenerate a shared token without owner approval.

Output

Return auth mode, secret-reference name, redirect/state result, authorized Workspace IDs in redacted form, verification status, and rotation owner.

Error Handling

Condition	Response
State mismatch	Reject the callback and start a new authorization attempt.
Redirect mismatch	Correct the registered exact URI; do not relax validation.
Workspace not authorized	Stop and require explicit user reauthorization.
Credential leaked	Revoke/regenerate, scrub artifacts, and record the incident.

Examples

The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.

mode=oauth; redirect=exact; state=valid; token=stored-by-reference; workspace-match=yes; writes=0

Resources

• Skill-specific official documentation
• Authentication
• Authentication
• Rate limits