The API Settings page allows you to create and edit JWT tokens that can be used to get Timepiece reports via REST API.
Documentation about the format of REST calls can be found in TiS Cloud - REST Reporting.
Viewing Tokens
Using the API Settings menu item on the main Timepiece reporting page, a user can open the API Settings page to view a list of tokens.
The display list only contains basic token information. The tokens themselves are displayed only at creation.
Users can only view their own tokens. Jira Admins can see everyone's tokens.
Token records contain these fields:
| Field | Description |
|---|---|
| Active | Sets whether a token is active or inactive. Inactive tokens will not be accepted by the system for authentication so you can deactivate a token if you think it is compromised. |
| Token ID | The auto-generated unique ID of the token. Serves no function other than distinguishing tokens from one another. |
| User | Shows the user which the token belongs to. The REST report requests sent with this token will be using the selected user's permissions on Jira. This field is automatically set with the current user while creating the token and cannot be changed later. |
| Created At | The date and time that the token was created. Set by the system and cannot be changed. |
| Expires At | The expiry date of the token. Expired tokens will not be accepted by the system for authentication. This field is mandatory but can also be set to a date far in the future (ex: 31 Dec 2099) so in practice, the set date can have no effect. The expiry date can be changed after creating the token. If you change the date to a point earlier than the current date, the token will simply not be accepted by the system. |
| Notes | This is the free format notes area for the token. You can put any text here that will make it easier for you to manage your tokens. |
Sometimes Atlassian rolls out updates gradually or an updated app requires a confirmation from Jira Admin.
If you can see other Timepiece admin pages but can't see the API Settings page under Jira Settings, then you can force an update by going to the Manage Apps page of your Jira. You will probably see an Update button under Timepiece (formerly Time in Status). Click it and refresh the page. You should now see the API Settings page.
Creating a Token
Using the Create New Token button at the top of the tokens list, users can create tokens only for themselves.
After creating the token, the UI will display the new token to you.
You copy the token from the dialog window and store it in a safe place as you will NOT be able to see the token again.
The tokens you get from here are used for authentication while accessing your Jira data through Timepiece. The tokens serve the same function as your Jira username and password.
You MUST keep the tokens safe.
If you suspect that the safety of a token is compromised, you can use the this page to deactivate or delete the token.
If you lose a token, you have to create a new one. There is no way to recover a lost token.
Editing a Token
You can edit an existing token using the Edit button in the Actions column.
Active/Inactive, Expiry Date, and Notes fields can be changed after the token is created.
Users can only edit their own tokens.
Deleting a Token
You can delete an existing token using the Delete button in the Actions column.
Please note that once a token is deleted, it is gone for good and cannot be recovered.
Users can only delete their own tokens. Jira admins can also delete other users' tokens.