Editing permission schemes using REST APIs

You need administrator rights in Jira to perform the tasks on this page.

Permission schemes only affect what users can do through the UI. Permissions schemes don’t restrict what users can do through scripting or the API.

To improve readability, all JSON results will be beautified, whereas the actual results will not.

Request URI

The base request URI for all APIs on this page is as follows:

CODE

http://{JIRA Instance Name}/rest/com.okapya.jira.checklist/latest/permissions

See Configuring checklists using REST APIs: Base configuration path for more help with the Request URI.

Permission Scheme APIs

Create permission scheme

POST [...]/permissions

You can create a new permission scheme in the field configuration.

Description

Example

Request

A JSON representation of the permission rule to create.

The JSON can be simplified to only include the required fields, such as the name.

Only the name and description fields can be specified.

JSON

{
  "name": "My sample scheme"
}

or

JSON

{
  "name": "My sample scheme",
  "description": "This scheme's goal is to give an example."
}

Response

Returns the full JSON representation of the newly created item.

JSON

{
    "id": 2,
    "name": "My sample scheme",
    "description": "",
    "rules": []
}

Get all permission schemes

GET [...]/permissions

You can get all permission schemes and their content, with the option to include metadata.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions?includeMetadata=true

Response

Returns the full JSON representation of the list of permission schemes.

The following example has the includeMetadata parameter set.

JSON

[
    {
        "id": 2,
        "name": "My sample scheme",
        "description": "",
        "rules": []
    },
    {
        "id": 1,
        "name": "Sample scheme",
        "description": "This is a sample scheme",
        "rules": [
            {
                "id": 1,
                "who": {
                    "type": {
                        "id": "ANY_LOGGED_IN_USER",
                        "name": "Any Logged in User",
                        "isDynamic": false,
                        "requiresValue": false
                    }
                },
                "what": {
                    "id": "ALL",
                    "name": "All Permissions",
                    "description": "Ability to do everything with checklist.",
                    "allowDynamicIdentifiers": false,
                    "indent": 0
                },
                "when": []
            },
            {
                "id": 3,
                "who": {
                    "type": {
                        "id": "USER_GROUP",
                        "name": "User Group",
                        "isDynamic": false,
                        "requiresValue": true
                    },
                    "value": {
                        "value": "jira-administrators",
                        "name": "jira-administrators"
                    }
                },
                "what": {
                    "id": "EDIT_ITEM",
                    "name": "Edit Item",
                    "description": "Ability to edit a checklist item name and convert to header.",
                    "allowDynamicIdentifiers": false,
                    "indent": 2
                },
                "when": []
            }
        ]
    }
]

Get a single permission scheme

GET [...]/permissions/{permissionSchemeId}

By providing a permission scheme ID, you can get the contents of a single scheme, with the option to include metadata.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123?includeMetadata=true

Response

Returns the full JSON representation of the requested scheme.

The following example does not have the includeMetadata parameter set.

JSON

[
    {
        "id": 2,
        "name": "My sample scheme",
        "description": "",
        "rules": []
    },
    {
        "id": 1,
        "name": "Sample scheme",
        "description": "This is a sample scheme",
        "rules": [
            {
                "id": 1,
                "who": {
                    "type": "ANY_LOGGED_IN_USER"
                },
                "what": "ALL",
                "when": []
            },
            {
                "id": 3,
                "who": {
                    "type": "USER_GROUP",
                    "value": "jira-administrators"
                },
                "what": "EDIT_ITEM",
                "when": []
            }
        ]
    }
]

Update a permission scheme

PUT [...]/permissions/{permissionSchemeId}

You can update the specified scheme’s content, with the option to include metadata in the response.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123?includeMetadata=true

Request

A JSON representation of the fields to update, including their values.

To keep updating simple, you only have to list the fields and values that you want to update.

Only the name and description fields can be specified.

JSON

{"name":"A new name for my scheme"}

or

JSON

{"description":"There is something new"}

Response

Returns the full JSON representation of the updated scheme.

JSON

{
    "id": 2,
    "name": "My sample scheme",
    "description": "The sample scheme's new description",
    "rules": []
}

See where a permission scheme is in use

GET [...]/permissions/{permissionSchemeId}/usage

You can query to find out how many field configuration contexts currently use the permission scheme.

	Description	Example
Response	Returns a JSON representation of the list of field configuration contexts (IDs and names) where the permission scheme is used.	JSON `[ { "id": "10101", "name": "DoD (Default context for DoD)" } ]`

Delete

DELETE [...]/permissions/{permissionSchemeId}

You can delete a permission scheme.

Permission Scheme Rules APIs

Create rule

POST [...]/permissions/{permissionSchemeId}/rules

You can create a new permission scheme in the field configuration, with the option to include metadata in the response.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123/rules?includeMetadata=true

Request

A JSON representation of the permission rule to create.

JSON

{
  "who": {
    "type": "SINGLE_USER",
    "value": "someUserName"
  },
  "what": "ALL",
  "when": [
    {
      "type": "PROJECT",
      "values": [
        "10010",
        "10001"
      ]
    },
    {
      "type": "ISSUE_TYPE",
      "values": [
        "3"
      ]
    }
  ]
}

Response

Returns the full JSON representation of the newly created item.

JSON

{
  "id": 4,
  "who": {
    "type": "SINGLE_USER",
    "value": "someUserName"
  },
  "what": "ALL",
  "when": [
    {
      "type": "PROJECT",
      "values": [
        "10010",
        "10001"
      ]
    },
    {
      "type": "ISSUE_TYPE",
      "values": [
        "3"
      ]
    }
  ]
}

Get all rules inside a permission scheme

GET [...]/permissions/{permissionSchemeId}/rules

You can get all of a permission scheme’s rules, with the option to include metadata.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123/rules?includeMetadata=true

Response

Returns the full JSON representation of the list of permission schemes.

The following example has the includeMetadata parameter set.

JSON

[
    {
        "id": 1,
        "who": {
            "type": {
                "id": "ANY_LOGGED_IN_USER",
                "name": "Any Logged in User",
                "isDynamic": false,
                "requiresValue": false
            }
        },
        "what": {
            "id": "ALL",
            "name": "All Permissions",
            "description": "Ability to do everything with checklist.",
            "allowDynamicIdentifiers": false,
            "indent": 0
        },
        "when": []
    },
    {
        "id": 3,
        "who": {
            "type": {
                "id": "USER_GROUP",
                "name": "User Group",
                "isDynamic": false,
                "requiresValue": true
            },
            "value": {
                "value": "jira-administrators",
                "name": "jira-administrators"
            }
        },
        "what": {
            "id": "EDIT_ITEM",
            "name": "Edit Item",
            "description": "Ability to edit a checklist item name and convert to header.",
            "allowDynamicIdentifiers": false,
            "indent": 2
        },
        "when": []
    },
    {
        "id": 4,
        "who": {
            "type": {
                "id": "SINGLE_USER",
                "name": "Single User",
                "isDynamic": false,
                "requiresValue": true
            },
            "value": {
                "value": "someUserName"
            }
        },
        "what": {
            "id": "EDIT_ITEM",
            "name": "Edit Item",
            "description": "Ability to edit a checklist item name and convert to header.",
            "allowDynamicIdentifiers": false,
            "indent": 2
        },
        "when": []
    }
]

Get a single rule from a permission scheme

GET [...]/permissions/{permissionSchemeId}/rules/{ruleId}

By providing a rule ID, you can get the contents of a single rule.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123/rules/1?includeMetadata=true

Response

Returns the full JSON representation of the requested scheme.

The following example does not have the includeMetadata parameter set.

JSON

{
    "id": 1,
    "who": {
        "type": "ANY_LOGGED_IN_USER"
    },
    "what": "ALL",
    "when": []
}

Update a rule inside a permission scheme

PUT [...]/permissions/{permissionSchemeId}/rules/{ruleId}

You can update the specified rule’s content.

Description

Example

Query parameters

OPTIONAL

includeMetadata can be appended as a query parameter to include metadata information such as translated labels.

[...]/permissions/123/rules/1?includeMetadata=true

Request

A JSON representation of the fields to update, including their values.

To keep updating simple, you only have to list the fields and values that you want to update.

JSON

{"what":"EDIT_CHECKLIST"}

or

JSON

{"who": {"type":"SINGLE_USER", "value":"someOtherUserName"}}

or

JSON

{"when": [{"type":"PROJECT", "values": ["1000"]}]}

Response

Returns the full JSON representation of the updated scheme.

JSON

{
    "id": 1,
    "who": {
        "type": "SINGLE_USER",
        "value": "someOtherUserName"
    },
    "what": "EDIT_CHECKLIST",
    "when": [
        {
            "type": "PROJECT",
            "values": [
                "1000"
            ]
        }
    ]
}

Delete a rule from a permission scheme

DELETE [...]/permissions/{permissionSchemeId}/rules/{ruleId}

You can delete a rule from a permission scheme.

Exceptions

For the list of potential exceptions, see Exceptions for configuration REST APIs: Permission schemes.