Skip to content
Docs
Project management

Asana

Let hires find, create, update, complete and comment on tasks in your Asana projects, and move them between sections.

Explore 10 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Asana, a hire can:

  • list your projects and their sections,
  • list a project's open tasks (or all of them), or one section's,
  • search tasks by the words in them,
  • read a task with its description and latest comments,
  • create tasks, assigned and with a due date, in the section you want,
  • change a task's title, description, due date or assignee, and mark it complete,
  • comment, and move a task to another section (another column on a board).

1. Choose how Roster signs in

  • A personal access token (quickest). In Asana, open the developer console (the form in Roster links there too), click Create new token, name it Roster, and copy it. What hires do shows as you, so you may want an Asana member just for Roster.
  • An OAuth app of yours. In the developer console, click Create new app, add the redirect URL Roster shows on the connection (it ends in /api/integrations/asana/oauth/callback), and copy its client ID and secret.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Asana and choose it.
  2. How Roster signs in: pick the way you chose above. Only its fields are shown.
  3. Paste the token, or the app's client ID and secret.
  4. Click Connect. With a token, Roster checks it with Asana, and the connection shows Connected as your Asana workspace and the token's owner. If Asana refuses it, Roster says so and saves nothing. With an OAuth app, then click Connect with Asana and allow it.

3. Give hires access

On the hire's Tools tab, click Give access on Asana:

  • Read only: it can list projects, sections and tasks, search and read tasks, and nothing else.
  • Read and write: it can also create, update and complete tasks, comment and move them between sections.
  • Workspaces: workspace names, one per line. Leave it empty for every workspace the account is in.
  • Projects: project names (or the number in a project's address). Leave it empty for every project in those workspaces. A task outside the list is refused, even if the hire knows its number.

Hires refer to tasks by their number (the last number in a task's address) and to projects and sections by name.

Watching for changes

A hire's responsibility can watch Asana: when tasks in its projects change, the hire is woken with the list. With no projects listed it watches the first 20 it can use, so list the ones that matter.

If something goes wrong

  • Search is slower or finds less on free workspaces: Asana's search is for paid plans, so on a free workspace the hire looks through each project's open tasks instead.
  • "Rate limit is used up": free workspaces allow 150 requests a minute. The hire waits and tries again.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Asana and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Asana: Settings → Apps → Developer apps (developer console) → Create new token. Hires' work shows as the token's owner.

For: How Roster signs in: Personal access token.

OAuth 2.0

From the app you made in Asana's developer console (My apps → Create new app).

For: How Roster signs in: An OAuth app of yours.

Requested scopes:

  • workspaces:read
  • projects:read
  • project_sections:read
  • tasks:read
  • tasks:write
  • stories:read
  • stories:write
  • users:read

Connection fields

Asana connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		A token is quickest. An OAuth app of yours lets Asana show Roster by name.

Choices: Personal access token (token); An OAuth app of yours (oauth).

Starts with: token.

Personal access token
token
Required · sealed secret		In Asana: Settings → Apps → Developer apps (developer console) → Create new token. Hires' work shows as the token's owner.

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From the app you made in Asana's developer console (My apps → Create new app).

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Asana per-hire limits
FieldWhat to provide
Workspaces
workspaces
Optional		Workspace names (or ids). Leave empty for every workspace the account is in.
Projects
projects
Optional		Project names (or ids from their address). Leave empty for every project in those workspaces.

Actions

10 actions: 5 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

10 of 10 actions. Open an action for its arguments and full input schema.

list_projectsRead only

The Asana projects this hire can use, with their workspaces.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_tasksRead only

A project's tasks (open ones unless asked), optionally only one section's.

Approval: Uses your workspace and hire approval settings.

Arguments for list_tasks
ArgumentTypeDetails
projectRequiredstringproject name or id
sectionOptionalstringonly tasks in this section, by name
include_doneOptionalbooleanSee input schema below.Default: false
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project name or id"
    },
    "section": {
      "description": "only tasks in this section, by name",
      "type": "string"
    },
    "include_done": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "project"
  ]
}
search_tasksRead only

Find tasks by words in their name or description, in the hire's projects (or one of them).

Approval: Uses your workspace and hire approval settings.

Arguments for search_tasks
ArgumentTypeDetails
textRequiredstringSee input schema below.
projectOptionalstringproject name or id
include_doneOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1
    },
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project name or id"
    },
    "include_done": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "text"
  ]
}
get_taskRead only

A task's description, assignee, due date, where it is, and its latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_task
ArgumentTypeDetails
taskRequiredstringtask id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^\\d{1,30}$",
      "description": "task id"
    }
  },
  "required": [
    "task"
  ]
}
create_taskRead and write

Create a task in a project, optionally in a section, assigned and with a due date.

Approval: Uses your workspace and hire approval settings.

Arguments for create_task
ArgumentTypeDetails
projectRequiredstringproject name or id
titleRequiredstringSee input schema below.
descriptionOptionalstringplain textDefault: ""
dueOptionalstringdue date like 2026-11-30, or "none" to clear it
assigneeOptionalstring"me", an email, or "none" to unassign
sectionOptionalstringa section of the project, by name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project name or id"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "plain text"
    },
    "due": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}|none)$",
      "description": "due date like 2026-11-30, or \"none\" to clear it"
    },
    "assignee": {
      "type": "string",
      "minLength": 1,
      "description": "\"me\", an email, or \"none\" to unassign"
    },
    "section": {
      "description": "a section of the project, by name",
      "type": "string"
    }
  },
  "required": [
    "project",
    "title"
  ]
}
update_taskRead and write

Change a task's title, description, due date or assignee. Only what's given changes.

Approval: Uses your workspace and hire approval settings.

Arguments for update_task
ArgumentTypeDetails
taskRequiredstringtask id
titleOptionalstringSee input schema below.
descriptionOptionalstringreplaces the description
dueOptionalstringdue date like 2026-11-30, or "none" to clear it
assigneeOptionalstring"me", an email, or "none" to unassign
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^\\d{1,30}$",
      "description": "task id"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "description": {
      "description": "replaces the description",
      "type": "string"
    },
    "due": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}|none)$",
      "description": "due date like 2026-11-30, or \"none\" to clear it"
    },
    "assignee": {
      "type": "string",
      "minLength": 1,
      "description": "\"me\", an email, or \"none\" to unassign"
    }
  },
  "required": [
    "task"
  ]
}
complete_taskRead and write

Mark a task complete (or not complete again).

Approval: Uses your workspace and hire approval settings.

Arguments for complete_task
ArgumentTypeDetails
taskRequiredstringtask id
doneOptionalbooleanSee input schema below.Default: true
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^\\d{1,30}$",
      "description": "task id"
    },
    "done": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "task"
  ]
}
commentRead and write

Comment on a task.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
taskRequiredstringtask id
textRequiredstringplain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^\\d{1,30}$",
      "description": "task id"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "description": "plain text"
    }
  },
  "required": [
    "task",
    "text"
  ]
}
list_sectionsRead only

A project's sections (its columns on a board), in order.

Approval: Uses your workspace and hire approval settings.

Arguments for list_sections
ArgumentTypeDetails
projectRequiredstringproject name or id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project name or id"
    }
  },
  "required": [
    "project"
  ]
}
move_to_sectionRead and write

Move a task to another section of its project (another column on a board), by name.

Approval: Uses your workspace and hire approval settings.

Arguments for move_to_section
ArgumentTypeDetails
taskRequiredstringtask id
sectionRequiredstringthe section's name
projectOptionalstringwhich of the task's projects, when it's in several
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^\\d{1,30}$",
      "description": "task id"
    },
    "section": {
      "type": "string",
      "minLength": 1,
      "description": "the section's name"
    },
    "project": {
      "description": "which of the task's projects, when it's in several",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "task",
    "section"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

S3-compatible storage

Let hires find and read files in buckets on Amazon S3, MinIO, Cloudflare R2, Wasabi, Ceph or any S3 API, and upload, share or delete only as you allow.

Basecamp

Projects, to-dos, messages and docs in Basecamp.

On this page

1. Choose how Roster signs in2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference