Asana connector setup

This page is the setup half — creating the OAuth app Asana needs in its own "My apps" console and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Asana.

1. Create the OAuth app in Asana's "My apps"

1. Open Asana's developer console and create a new app under My apps — this is your own app, not Botseon's. Self-registration immediately issues a client id and secret; there is no mandatory pre-launch review.

2. Under Redirect URL, paste the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/asana/callback
   

3. Save. The console shows you a Client ID and a Client secret — copy both now.

On a workspace with Enterprise "approval mode" turned on, a super admin must approve this app before members can authorize it — that is a member's reality, not something this build controls.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately). Every scope below must be registered on the app before the authorize call, or Asana returns forbidden_scopes:

Read:

• tasks:read — search and read tasks.
• projects:read — list and read projects.
• users:read — see who is in the workspace.

Write, on top of the read set:

• tasks:write — create a task and change its fields.
• stories:write — add a comment to a task. A comment is authored as you and reaches people outside the organisation, so this tool's approval card names the task.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug asana \
  --client-id <the client ID from step 1> \
  --auth-url https://app.asana.com/-/oauth_authorize \
  --token-url https://app.asana.com/-/oauth_token \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug asana says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

• asana.search_tasks — search tasks in a workspace. Asana's search needs a paid plan; on a free workspace the call fails with "Asana search needs a paid Asana plan for this workspace".
• asana.get_task — one task and its fields.
• asana.list_projects — the projects in a workspace.
• asana.create_task — creates a task in a project. Tagged write; the approval card names the project.
• asana.update_task — changes a task's fields. Tagged write; the approval card names the task.
• asana.comment — adds a comment to a task. Tagged write and external_send, because a comment reaches people outside the organisation; the approval card names the task and the comment's text is disclosed on the card.

Access tokens last one hour; the rate limit is 150 calls/min on a free-tier token and 1,500/min on a paid one. Asana's EU data centre is Enterprise-only, opt-in and through sales, and whether it changes the API base URL is unverified, so this connector calls https://app.asana.com/api/1.0 regardless.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.