Connect Jira with an API token

An API token lets Planning Poker Web read your Jira issues and write the accepted estimate back, without going through a sign-in screen. This page explains how to create one, what it is allowed to do, and what to check when something does not work. It applies to Jira Cloud (an address like your-team.atlassian.net). Jira Data Center is not supported.

Before you start

• You need the permission to manage planning poker in your organization. Owners have it by default.
• The Jira account behind the token needs, in each project you will use, the permission to browse the project (to import issues) and to edit issues (to write the estimate back). If you only import and never send estimates back, browsing is enough.
• Prefer a shared account made for this, such as planningpoker@your-company.com, rather than a person's own account. The estimate appears in the issue history under that account's name, and a personal token stops working the day that person leaves or loses access.

Step 1: create the token in Atlassian

1. Sign in to Atlassian with the account you chose and open id.atlassian.com → Security → API tokens.
2. Choose Create API token. Use the plain one, not "Create API token with scopes": a token with scopes does not work with this connection.
3. Give it a name you will recognise, such as "Planning Poker Web", and pick how long it should last.
4. Copy the token right away. Atlassian shows it only once. If you lose it, create a new one.

If you do not see the option, your Atlassian administrator may have restricted who can create tokens. Ask them to allow it for the account you chose.

Step 2: connect it in Planning Poker Web

1. Open Settings → Integrations, choose Jira and then Connect, and pick the API token option.
2. Fill in the three fields:
   • Jira site: the address of your Jira, for example https://your-team.atlassian.net. Only https://….atlassian.net addresses are accepted.
   • Account e-mail: the e-mail of the Atlassian account that created the token.
   • API token: the token you copied.
3. Choose Test. If it works, you will see the name of the Jira account. Your token is stored encrypted and is never shown again.
4. In the Configure step, choose whether the accepted estimate goes back to Jira and into which field. See Send estimates back.

How it works

Every request is made from our servers to your Jira, signed with your e-mail and token. The token carries the same permissions as the account that created it, no more and no less. Planning Poker Web does only these things:

• Reads your projects, and for a project its statuses, issue types, epics and sprints, so the import dialog can offer the filters.
• Reads issues: the key, the title and the description, to bring them into a room.
• Writes one number on one issue: the accepted estimate, in the field you chose.

It never creates or deletes issues, never changes their status, and never adds comments. Sprints are read only if the account can open the project's board in Jira Software. Without it, the sprint filter is simply empty.

If it does not work

• "Jira rejected the credentials": the e-mail or the token is wrong, the token was revoked, or it has expired. Create a new token and use Reconnect.
• "Jira denied access (403)": Jira understood the key but refused the request. Check, in this order: that the account really has access to Jira on that site (open the site signed in as that account), that it can browse the project (and edit issues, for estimates), that your Atlassian administrator has not limited API access to certain networks, and that the token is the plain kind, not the one "with scopes". Jira's own explanation, when it gives one, appears after the colon.
• Your project is not in the list: the account cannot browse it. Add the account to the project, or use an account that already belongs to it.
• The estimate was not sent, saying the field is not on the screen: the field must be on the issue's edit screen in that project. Jira has two similar fields, Story points and Story point estimate; choose the one your board displays.
• "Use your Jira Cloud address": the site field has to look like https://your-team.atlassian.net, with no path after it.

When the token expires or you want to stop

Atlassian tokens do not last forever. When yours expires, create a new one and use Reconnect; your estimate settings are kept. To stop the connection, choose Disconnect in Planning Poker Web and, if you want, revoke the token in id.atlassian.com → Security → API tokens. After that, nothing can reach your Jira.