Custom User Role API

General Information

Create an API Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations.

Create Custom User Role

Create custom user role request is used to add new custom user role in OpsGenie and is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method
URL

JSON Body Fields

Fields
Mandatory
Description

name

true

Name of the defined custom user role

extendedRole

false

Default user role which is extended. Possible values are
user, observer and stakeholder. Default value is user

grantedRights

false

You can refer User Right Prerequisites for detailed information about possible values of rights.

disallowedRights

false

You can refer User Right Prerequisites for detailed information about possible values of rights.

Sample Request

curl -X POST  'https://api.opsgenie.com/v2/roles'
	--header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
  	--header 'Content-Type: application/json'
  	--data
'{
	"name": "UserRoleName",
	"extendedRole": "user",
	"grantedRights": ["logs-page-access"],
	"disallowedRights":["alert-update-priority", "alert-escalate"]
 }'

Response

{
    "result": "Created",
    "data": {
        "id": "187f70c4-0e24-4465-b04d-3f651bf2f2f7",
        "name": "UserRoleName"
    },
    "took": 1.326,
    "requestId": "27ebded8-70c5-40d9-ae14-24c4019d3e4d"
}

Get Custom User Role

Get custom user role request is used to search and retrieve custom user role in OpsGenie. It takes the following parameters:

In-Line Parameters

Referred Name
Description

identifier

Identifier of the custom user role

Query Parameters

Parameter
Mandatory
Description

identifierType

false

Type of the custom user role identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/roles/187f70c4-0e24-4465-b04d-3f651bf2f2f7?identifierType=id'
		--header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": {
        "id": "187f70c4-0e24-4465-b04d-3f651bf2f2f7",
        "name": "UserRoleName",
        "extendedRole": "user",
        "grantedRights": [
            "logs-page-access"
        ],
        "disallowedRights": [
            "alert-escalate",
            "alert-update-priority"
        ]
    },
    "took": 0.222,
    "requestId": "8f987dbb-6724-4bc9-b4c2-932a68f6779f"
}

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/roles/UserRoleName?identifierType=name'
		--header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": {
        "id": "187f70c4-0e24-4465-b04d-3f651bf2f2f7",
        "name": "UserRoleName",
        "extendedRole": "user",
        "grantedRights": [
            "logs-page-access"
        ],
        "disallowedRights": [
            "alert-escalate",
            "alert-update-priority"
        ]
    },
    "took": 0.222,
    "requestId": "8f987dbb-6724-4bc9-b4c2-932a68f6779f"
}

Update Custom User Role

Update custom user role request is used to update a custom user role in OpsGenie and is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

In-Line Parameters

Referred Name
Description

identifier

Identifier of the custom user role

Query Parameters

Parameter
Mandatory
Description

identifierType

false

Type of the custom user role identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Field

Fields
Mandatory
Description

name

false

Name of the defined custom user role

extendedRole

false

Default user role which is extended. Possible values are
user, observer and stakeholder. Default value is user

grantedRights

false

You can refer User Right Prerequisites for detailed information about possible values of rights.

disallowedRights

false

You can refer User Right Prerequisites for detailed information about possible values of rights.

Sample Request

curl -X PUT 'https://api.opsgenie.com/v2/roles/187f70c4-0e24-4465-b04d-3f651bf2f2f7?identifierType=id'
	--header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
  	--header 'Content-Type: application/json'
  	--data
'{
    "name": "UpdateUserRoleName",
    "extendedRole": "user",
    "grantedRights": ["maintenance-edit"],
    "disallowedRights":["alert-add-note","alert-update-priority", "alert-close", 			"alert-close-all"]
}'

Response

{
  "result":"Updated",
  "data":{
    "id":"187f70c4-0e24-4465-b04d-3f651bf2f2f7",
    "name":"UpdatedUserRoleName"
  },
  "took": 0.049,
  "requestId": "b4baea0e-d86c-4a77-9b19-e7566c3f65cc"
}

Sample Request

curl -X PUT 'https://api.opsgenie.com/v2/roles/UserRoleName?identifierType=name'
	--header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
  	--header 'Content-Type: application/json'
  	--data
'{
    "name": "UpdateUserRoleName",
    "extendedRole": "user",
    "grantedRights": ["maintenance-edit"],
    "disallowedRights":["alert-add-note","alert-update-priority", "alert-close", 			"alert-close-all"]
}'

Response

{
  "result":"Updated",
  "data":{
    "id":"187f70c4-0e24-4465-b04d-3f651bf2f2f7",
    "name":"UpdatedUserRoleName"
  },
  "took": 0.063,
  "requestId": "efcbeafd-8a53-42f1-94d2-2df8d951896b"
}

Delete Custom User Role

Delete custom user role request is used to delete custom user role in OpsGenie and is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

In-Line Parameters

Referred Name
Description

identifier

Identifier of the custom user role

Query Parameters

Parameter
Mandatory
Description

identifierType

false

Type of the custom user role identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/roles/187f70c4-0e24-4465-b04d-3f651bf2f2f7a?identifierType=id'
 		--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "result": "Deleted",
    "took": 0.241,
    "requestId": "6e9b0fcd-4c3b-4416-b6d6-79e7c7c02647"
}

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/roles/UserRoleName?identifierType=name'
 		--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "result": "Deleted",
    "took": 0.241,
    "requestId": "6e9b0fcd-4c3b-4416-b6d6-79e7c7c02647"
}

List Custom User Roles

List custom user roles request is used to list custom user roles in OpsGenie.

HTTP Method
URL

Query Parameters

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/roles'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": [
        {
            "id": "187f70c4-0e24-4465-b04d-3f651bf2f2f7",
            "name": "UserRoleName"
        }
    ],
    "took": 0.076,
    "requestId": "fd6e3216-8cd3-4c1e-a050-39d194997f16"
}

Some user rights require other user rights to be granted. In other words, some user rights are prerequisites for other user rights to be assigned. The detailed schema could be found in User Right Prerequisites

User Right Prerequisites

The table below shows rights to be granted, the required rights needed to be granted and required role as well.

Right
Prerequisite
Required Role

who-is-on-call-show-all

-

user

notification-rules-edit

-

user

quiet-hours-edit

-

user

alerts-access-all

-

user

reports-access

-

user

logs-page-access

-

user

maintenance-edit

-

user

contacts-edit

-

observer, stakeholder, user

profile-edit

-

observer, stakeholder, user

login-email-edit

-

observer, stakeholder, user

profile-custom-fields-edit

profile-edit

user

configurations-read-only

who-is-on-call-show-all, alerts-access-all, contacts-edit

user

configurations-edit

configurations-read-only

user

configurations-delete

configurations-edit

user

billing-manage

configurations-edit

user

alert-action

-

user

alert-create

alert-action

user

alert-add-attachment

alert-action

user

alert-delete-attachment

alert-action

user

alert-add-note

alert-action

user

alert-acknowledge

alert-action

user

alert-unacknowledge

alert-action

user

alert-snooze

alert-action

user

alert-escalate

alert-action

user

alert-close

alert-action

user

alert-delete

alert-close

user

alert-take-ownership

alert-action

user

alert-assign-ownership

alert-action

user

alert-add-recipient

alert-action

user

alert-add-team

alert-action

user

alert-edit-tags

alert-action

user

alert-edit-details

alert-action

user

alert-custom-action

alert-action

user

alert-update-priority

alert-action

user

alert-acknowledge-all

alert-acknowledge

user

alert-close-all

alert-close

user

incident-create

alert-create

user

incident-add-stakeholder

alert-add-recipient

user

incident-add-responder

alert-add-recipient

user

incident-resolve

alert-action

user

incident-reopen

alert-action

user

mass-notification-create

alert-action

user

service-access-status

-

observer, stakeholder, user

Custom User Role API