API
You can manage your Jira shares via web API by generating API Key. To do this, perform the following steps:
Go to the External Share for Jira admin panel and click on the API Keys tab. This will send you to a screen with all previously generated keys.
Click on Create new API key. API key creation popup will appear.
Setup your API key and copy or download it. The template has the following fields:
Key Name - provide your name for the API key, up to 40 characters long.
Key Value - non-modifable field, shows the value of the key.
Reveal - reveals the key. This is NOT one time operation - you can reveal the key at any time.
Download - downloads the key to the selected location.
Get Shares - determines whether get operation is allowed for the key.
List Shares - determines whether list operation is allowed for the key.
Create Shares - determines whether create operation is allowed for the key.
Edit Shares - determines whether edit operation is allowed for the key.
Delete Shares - determines whether delete operation is allowed for the key.
Not valid before - set the start date for key validity.
Not valid after - set the invalidation date for the key.
Allowed IPs - set IPs or IP range that can use the key.
Description - description of the key. Maximum 4000 characters.
Creation Time - non-modifable field, the time when the key was created.
Last Modification Time - non-modifable field, the time when the key was last modified.
Last Usage Time - non-modifable field, the time when the key was last used.
Usage Count - non-modifable field, counter that shows how many times the key was used.
Using the Web API with API key
With key generated, you can now make a call to Web API. First of all, set Authorization and Content-Type headers in your REST client.
Authorization: 'Bearer { KEY_VALUE }'Content-Type: 'application/json'
With the headers set, you can perform the following operations: GET, LIST, CREATE, and DELETE.
GET OPERATION
This operation allows you to retrieve a single share, or its activity, based on share uuid. This operation does not accept any additional options and returns JSON with Share data/Share activity data.
Example Call:
GET https://jira.external-share.com/webapi/share/{ SHARE_UUID }GET https://jira.external-share.com/webapi/share/{ SHARE_UUID }/activityGET /rest/servicedeskapi/request/{issueIdOrKey}/approval
LIST OPERATION
This operation allows you to retrieve a sorted list of shares based on the options passed. You need to have an access to shared issues to be able to list shares. You can pass the following options as request parameters:
sort - share field by which the list will be sorted. The default value is “id”. In general, you can sort by any Share’s field as long as it is in a snake_case instead of camelCase. For example, you can sort by Issue ID, by passing “issue_id” (instead of issueId as returned in the JSON).
sortOrder - order in which list will be sorted. Pass “asc” for ascending list; “desc” for descending list. “asc” is default.
limit - defines how many shares will be returned in a single call. Default is 100.
offset - defines how many positions from the start of the list will be ommited. Combined with the limit parameter, this parameter may help perform concurrent calls. The default value is 0, which means the very first share on the list will be returned.
issueId - returns all shares associated with a specific issue ID.
userId - returns all shares for a given user ID.
projectId - returns all shares in the selected project.
NOTE: If you are an administrator, you may ommit passing userId and/or projectId - this will result in returning all shares from all projects you have admin rights. However, if you are not an administrator, the call will not be accepted and FORBIDDEN http status will be returned.
Example Call:
GET https://jira.external-share.com/webapi/share?sort=uuid&sortOrder=desc&projectId=10000CREATE OPERATION
This operation allows you to create a new share, whether it is a share of an Issue, Board or JQL and returns its JSON representation. The operation requires passing request body with mandatory fields:
type - defines share type. Possible values: “ISSUE”, “BOARD”, “JQL”, “TIMELINE”.
issueId - required for ISSUE type shares.
projectId - required for BOARD, JQL and TIMELINE type shares.
board - can be used to specify a specific board in the project.
You may also pass additional fields:
Parameter Name |
Description |
Default |
|---|---|---|
password |
Sets password for share. |
null |
expiration |
Expiration timestamp in epoch miliseconds. |
null |
fieldsConfig |
List of fields added to share with its permissions. Possible values for fieldPermissions: “VIEW”, “VIEW_CONTENT”, “ADD”, ”EDIT”.
Default: If a permission is omitted, it is treated as disabled ( Example JSON body:
|
null |
selectedUsersConfig |
Pass this object to define list of users that can access the share. You can pass the following fields in this configuration:
Note: If in Project Config > Security, the “Selected users” option is set to Required (rather than Allowed), the config specified in that config will be used. |
null |
expirationExpression |
object with |
null |
jql |
generated: |
|
board |
|
null |
useProjectConfig |
|
false |
Example Call:
POST https://jira.external-share.com/webapi/share{"issueId": "10001","type": "ISSUE","expiration": 1649700933954,"customFields": [{"id":"10020"}, {"id":"10021"}],"selectedUsersConfig": {"allowed": true,"allowedNotification": false,"list": [{"email": "expl@expl2.com"}, {"email": "expl@expl.com"}]}}
UPDATE OPERATION
This operation allows you to update an existing UUID link.
Example Call:
PUT https://jira.external-share.com/webapi/share/{YOUR-ISSUE-UUID}DELETE OPERATION
This operation allows you to delete a single share based on its share uuid. It does not accept any additional options. Upon successful execution, it returns no content (HTTP 204). If an error occurs, a JSON with the error message will be provided.
Example Call:
DELETE https://jira.external-share.com/webapi/share/{ SHARE_UUID }
An example rule: Automatically create an External Share link for every new issue.