Taskade API Authentication

Send a Bearer token in the Authorization header on every request. REST API v1, Action API v2, and the MCP servers all accept it.

Page type: How-to guide. Use it when you know the goal and need the steps.

TL;DR: To act as yourself, create a personal access token at taskade.com/settings/api and send Authorization: Bearer $TASKADE_TOKEN. To act for other users, use OAuth 2.0 with PKCE. An access token lasts 1 hour, and each refresh returns a new refresh token.

Before you start

• A Taskade account with a verified email address. Taskade does not create a token or an OAuth application for an unverified account.
• curl in a terminal. The PKCE example also uses openssl.
• For OAuth 2.0, a redirect URI that your app controls.

Choose a credential

Personal access tokens

Personal access tokens authenticate requests as yourself. They work well for server scripts, the local Workspace MCP server, and early development.

Create a token

1. Go to taskade.com/settings/api.
2. Go to Personal access tokens and click Create token.
3. Give the token a descriptive name.
4. Copy the token immediately. Taskade shows it only once.
5. Save the token in your terminal:

export TASKADE_TOKEN="tskdp_your_token_here"

A personal access token starts with the prefix tskdp_. You can hold up to 5 tokens per account, and your email must be verified to create one.

A personal access token grants full access to your account. Treat it like a password.

Never commit or share the token. Store it in an environment variable or secret manager.

Use a token

Send it in the Authorization header on every request:

# REST API v1
curl -s https://www.taskade.com/api/v1/me/projects \
  -H "Authorization: Bearer $TASKADE_TOKEN"

# Action API v2
curl -s -X POST https://www.taskade.com/api/v2/listMyProjects \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

A valid token returns ok: true and the projects that your account can open:

{ "ok": true, "items": [{ "id": "Pj8sK2nV4wQx6ZbE", "name": "API quickstart" }] }

A missing, wrong, or revoked token returns 401:

{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED", "statusMessage": "Unauthorized" }

The local Workspace MCP server (@taskade/mcp-server) reads the token from the TASKADE_API_KEY environment variable, not from TASKADE_TOKEN. See Workspace MCP.

Use a personal token with hosted MCP

The hosted endpoint at https://www.taskade.com/mcp accepts the same tskdp_… personal access token as the public APIs:

POST https://www.taskade.com/mcp
Authorization: Bearer tskdp_your_token_here
Content-Type: application/json

Choose this option for a script, server process, CI job, or MCP client where you control the request headers.

The connection acts as your Taskade account. Personal tokens carry no OAuth scopes and grant their owner's access. Do not distribute them.

For Claude, Cursor, and other interactive clients with remote MCP OAuth support, prefer the OAuth flow. The flow keeps a full-account personal token out of the client. It also gives each user a separate consent flow.

OAuth 2.0

Use OAuth 2.0 when your application acts on behalf of other users. Each user signs in and grants access.

Also use OAuth 2.0 for interactive clients that connect to hosted MCP. Header-controlled scripts can use a personal access token instead.

Endpoints

Register an application

Go to taskade.com/settings/api → OAuth2 Applications. Click Create application, then register your app and set its redirect URI(s). Your email must be verified before you can create an application.

Taskade gives you a Client ID and Client Secret. Save them, and the redirect URI, in your terminal:

export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"
export REDIRECT_URI="https://your-app.example.com/callback"

Authorization Code flow (with PKCE)

Taskade supports the Authorization Code grant with PKCE (S256), the recommended flow for both confidential and public clients.

1. Redirect the user to /oauth2/authorize with client_id, redirect_uri, response_type=code, code_challenge, and code_challenge_method=S256. If the token must reach the hosted MCP server, add scope=mcp. Taskade supports no other scope, and the REST and Action APIs ignore scope.
2. Exchange the returned code at /oauth2/token with grant_type=authorization_code and your code_verifier.
   • For confidential apps, also send client_secret.
   • For public clients, omit client_secret.
3. Store the access_token and refresh_token. The access token is valid for 1 hour.

Generate the PKCE pair. Most implementation errors occur in this step:

# code_verifier: a high-entropy random string
code_verifier=$(openssl rand -base64 96 | tr -d '\n=+/' | cut -c1-64)

# code_challenge = BASE64URL( SHA256(code_verifier) )
code_challenge=$(printf '%s' "$code_verifier" \
  | openssl dgst -binary -sha256 \
  | openssl base64 | tr -d '=\n' | tr '+/' '-_')

Send code_challenge (with code_challenge_method=S256) on the authorize request. Then send the original code_verifier on the token exchange that follows.

Exchange the code for tokens

Your redirect URI receives the authorization code in the code query parameter. Save it, then exchange it in the same terminal that holds code_verifier:

export AUTH_CODE="code_from_the_redirect"

curl -s -X POST https://www.taskade.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "code_verifier=$code_verifier" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "redirect_uri=$REDIRECT_URI"

A public client omits the client_secret line. The response carries both tokens:

{
  "access_token": "eyJhbGciOi…",
  "refresh_token": "…",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Send access_token as Authorization: Bearer <access_token> on each API or MCP request.

Refresh an expired token

Access tokens expire after one hour. Exchange the stored refresh token for a new pair:

export REFRESH_TOKEN="your_stored_refresh_token"

curl -s -X POST https://www.taskade.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

Every refresh request must send client_id. A confidential app must also send client_secret, the same as on the code exchange. A public client omits the client_secret line.

The response has the same shape as the code exchange. It carries a new refresh_token, and the old refresh token stops working:

{
  "access_token": "eyJhbGciOi…",
  "refresh_token": "a_new_refresh_token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Store the new refresh token before you send the next request. Each refresh token works once:

Taskade supports the authorization_code and refresh_token grants only. Taskade rejects password, implicit, and client_credentials.

Scopes and the hosted MCP

When you use OAuth, the hosted MCP server at https://www.taskade.com/mcp requires an access token with the mcp scope. When you add the server URL, MCP clients (Claude Desktop, Cursor, Claude Code) do this handshake automatically, with dynamic client registration.

Personal access tokens do not use OAuth scopes. If you set the Authorization header yourself, as shown earlier, use a personal token.

Fix common errors

The token endpoint returns OAuth errors with status 400, in the RFC 6749 shape. For example, an expired or reused code returns:

{ "error": "invalid_grant", "error_description": "Grant not found" }

Security best practices

• Never expose tokens in client-side code. Personal tokens grant full account access.
• Use OAuth, not personal tokens, for an app that more than one person uses.
• Store refresh tokens encrypted at rest. They are long-lived.
• Rotate personal tokens periodically. You can keep up to 5 active.
• Always use HTTPS.

Next steps

• Quickstart: make your first call with a personal access token.
• Personal access tokens: limits and token management.
• Action API guide: call the API with the token you created.
• Hosted MCP: connect an MCP client with OAuth or a personal token.