Skip to content
Docs
Project management

Jira

Let hires search, read, create, update, move, comment on and assign Jira issues and plan sprints, on Jira Cloud or your own Jira Data Center.

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

With Jira, a hire can:

  • list your projects and search issues with JQL, the way your team already does,
  • read an issue with its description, labels and latest comments,
  • create issues, change their summary, description, labels or priority,
  • move an issue to another status by name ("move WEB-12 to In Progress"), through your workflow,
  • comment, assign an issue to someone by name or email, or unassign it,
  • see a project's active and upcoming sprints and move an issue into one.

It works on Jira Cloud (atlassian.net) and on Jira Data Center or Server that you run yourself.

1. Choose how Roster signs in

You useSign in withYou need
Jira CloudEmail and API tokenan Atlassian account and an API token
Jira CloudAn OAuth app of yoursan OAuth 2.0 app at developer.atlassian.com
Jira Data Center or ServerPersonal access tokena personal access token from your Jira

What hires do shows as the account the token or app belongs to, so you may want a Jira account just for Roster, with access to the projects hires work in.

Jira Cloud: an API token

  1. Open your Atlassian API tokens (the form in Roster links there too), signed in as the account hires should act as.
  2. Click Create API token, name it Roster and copy it.

Jira Cloud: an OAuth app

  1. At developer.atlassian.com/console/myapps, click Create → OAuth 2.0 integration and name it Roster.
  2. Under Permissions, add Jira API with read:jira-work, write:jira-work and read:jira-user, and for sprints the Jira Software scopes read:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software and read:project:jira.
  3. Under Authorization, set the callback URL to the address Roster shows on the Jira connection. It ends in /api/integrations/jira/oauth/callback.
  4. Under Settings, copy the Client ID and Secret.

Jira Data Center or Server: a personal access token

  1. In Jira, click your avatar → Profile → Personal Access Tokens → Create token.
  2. Name it Roster, choose when it expires, and copy it.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Jira and choose it.
  2. How Roster signs in: pick the way you chose above. Only its fields are shown.
  3. Paste the email and API token, the personal access token, or the OAuth app's client ID and secret.
  4. Jira address: the address you open Jira at, like https://acme.atlassian.net, or your own server's address with any path, like https://jira.example.com/jira.
  5. Click Connect. With an API token or a personal access token, Roster asks Jira who it belongs to, and the connection shows Connected as that account and your site. If Jira refuses it, Roster says so and saves nothing. With an OAuth app, then click Connect with Jira on the new connection, choose your site and click Accept.

3. Give hires access

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

  • Read only: it can list projects, search and read issues and see sprints, and nothing else.
  • Read and write: it can also create, update, move, comment on and assign issues and add them to sprints.
  • Projects: project keys like WEB. Leave it empty for every project the account can reach. Anything outside the list is refused, including searches: a hire's JQL only ever runs inside its projects.

Hires refer to issues by key, like WEB-12, and to statuses, people and sprints by name. When an issue can't move to the status asked for, the hire is told which statuses it can move to.

Watching for changes

A hire's responsibility can watch Jira: when issues in its projects change, the hire is woken with the list. Checking is one search and costs nothing when nothing changed.

If something goes wrong

  • "Didn't accept the connection's credential": the API token or personal access token was revoked or expired, or the email doesn't match the token's account.
  • "The app was approved for … not …": with an OAuth app, connect again and pick the site in your Jira address.
  • "Can't move to …": your workflow has no transition from the issue's status to that one; the message lists the ones it has.
  • Sprints are empty: sprints come from Scrum boards; a project with only a Kanban board has none.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Jira 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.

User name and password or key pair

The email of the Atlassian account hires act as. Make the token at id.atlassian.com → Security → API tokens.

For: How Roster signs in: Jira Cloud: email and API token.

API key or access token

In Jira: your avatar → Profile → Personal Access Tokens → Create token.

For: How Roster signs in: Jira Data Center or Server: personal access token.

OAuth 2.0

From the OAuth 2.0 (3LO) app you made at developer.atlassian.com.

For: How Roster signs in: Jira Cloud: an OAuth app of yours.

Requested scopes:

  • read:jira-work
  • write:jira-work
  • read:jira-user
  • read:board-scope:jira-software
  • read:sprint:jira-software
  • write:sprint:jira-software
  • read:project:jira
  • offline_access

Connection fields

Jira connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		Jira Cloud (atlassian.net) with an API token is quickest. Data Center and Server use a personal access token.

Choices: Jira Cloud: email and API token (cloud-token); Jira Cloud: an OAuth app of yours (cloud-oauth); Jira Data Center or Server: personal access token (datacenter).

Starts with: cloud-token.

Atlassian account email
email
Required		The email of the Atlassian account hires act as. Make the token at id.atlassian.com → Security → API tokens.

Shown when signIn: cloud-token.

API token
apiToken
Required · sealed secret		Use the value for your account or connection.

Shown when signIn: cloud-token.

Personal access token
personalToken
Required · sealed secret		In Jira: your avatar → Profile → Personal Access Tokens → Create token.

Shown when signIn: datacenter.

OAuth app client ID
clientId
Optional		From the OAuth 2.0 (3LO) app you made at developer.atlassian.com.

Shown when signIn: cloud-oauth.

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

Shown when signIn: cloud-oauth.

Jira address
url
Required		The address you open Jira at: https://acme.atlassian.net for Cloud, or your own server's address (with any path, like /jira).

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.

Jira per-hire limits
FieldWhat to provide
Projects
projects
Optional		Project keys like WEB, one per line. Leave empty for every project the account can reach.

Actions

10 actions: 4 only read and 6 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 Jira projects this hire can use, with their keys.

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": {}
}
search_issuesRead only

Search issues with JQL, e.g. assignee = currentUser() AND statusCategory != Done, or text ~ "login". Most recently updated first unless the JQL says ORDER BY.

Approval: Uses your workspace and hire approval settings.

Arguments for search_issues
ArgumentTypeDetails
jqlOptionalstringa JQL query; empty for the latest issuesDefault: ""
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "jql": {
      "default": "",
      "description": "a JQL query; empty for the latest issues",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
get_issueRead only

An issue's description, status, assignee, labels and latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_issue
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    }
  },
  "required": [
    "key"
  ]
}
create_issueRead and write

Create an issue in a project.

Approval: Uses your workspace and hire approval settings.

Arguments for create_issue
ArgumentTypeDetails
projectRequiredstringproject key, e.g. WEB
summaryRequiredstringSee input schema below.
typeOptionalstringissue type name, e.g. Task, Bug, StoryDefault: "Task"
descriptionOptionalstringplain text; blank lines start new paragraphsDefault: ""
labelsOptionalstring[]See input schema below.Default: []
priorityOptionalstringa priority name, e.g. High
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,19}$",
      "description": "project key, e.g. WEB"
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "type": {
      "default": "Task",
      "description": "issue type name, e.g. Task, Bug, Story",
      "type": "string"
    },
    "description": {
      "default": "",
      "description": "plain text; blank lines start new paragraphs",
      "type": "string"
    },
    "labels": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\S+$"
      }
    },
    "priority": {
      "description": "a priority name, e.g. High",
      "type": "string"
    }
  },
  "required": [
    "project",
    "summary"
  ]
}
update_issueRead and write

Change an issue's summary, description, labels or priority. Only what's given changes.

Approval: Uses your workspace and hire approval settings.

Arguments for update_issue
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
summaryOptionalstringSee input schema below.
descriptionOptionalstringreplaces the description; plain text
labelsOptionalstring[]replaces the labels
priorityOptionalstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "description": "replaces the description; plain text",
      "type": "string"
    },
    "labels": {
      "description": "replaces the labels",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\S+$"
      }
    },
    "priority": {
      "type": "string"
    }
  },
  "required": [
    "key"
  ]
}
transition_issueRead and write

Move an issue to another status by name, e.g. In Progress or Done, through its workflow.

Approval: Uses your workspace and hire approval settings.

Arguments for transition_issue
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
statusRequiredstringthe status to move to, or the transition's name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    },
    "status": {
      "type": "string",
      "minLength": 1,
      "description": "the status to move to, or the transition's name"
    }
  },
  "required": [
    "key",
    "status"
  ]
}
commentRead and write

Comment on an issue.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
bodyRequiredstringplain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "plain text"
    }
  },
  "required": [
    "key",
    "body"
  ]
}
assign_issueRead and write

Assign an issue to someone by name or email, or "none" to unassign.

Approval: Uses your workspace and hire approval settings.

Arguments for assign_issue
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
assigneeRequiredstringa name or email, or "none"
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    },
    "assignee": {
      "type": "string",
      "minLength": 1,
      "description": "a name or email, or \"none\""
    }
  },
  "required": [
    "key",
    "assignee"
  ]
}
list_sprintsRead only

A project's active and upcoming sprints, from its Scrum boards.

Approval: Uses your workspace and hire approval settings.

Arguments for list_sprints
ArgumentTypeDetails
projectRequiredstringproject key, e.g. WEB
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,19}$",
      "description": "project key, e.g. WEB"
    }
  },
  "required": [
    "project"
  ]
}
add_to_sprintRead and write

Move an issue into one of its project's active or upcoming sprints, by the sprint's name.

Approval: Uses your workspace and hire approval settings.

Arguments for add_to_sprint
ArgumentTypeDetails
keyRequiredstringissue key, e.g. WEB-12
sprintRequiredstringthe sprint's name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^([A-Za-z][A-Za-z0-9_]{0,19})-(\\d+)$",
      "description": "issue key, e.g. WEB-12"
    },
    "sprint": {
      "type": "string",
      "minLength": 1,
      "description": "the sprint's name"
    }
  },
  "required": [
    "key",
    "sprint"
  ]
}

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

ClickUp

Let hires find, create, update, close and comment on tasks in your ClickUp spaces and lists.

Linear

Let hires find, create, comment on and move issues, as themselves or with your API key.

On this page

1. Choose how Roster signs inJira Cloud: an API tokenJira Cloud: an OAuth appJira Data Center or Server: a personal access token2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference