Custom User Role API

🚧
If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

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
POST	https://api.opsgenie.com/v2/roles

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:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/roles/:identifier

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

HTTP Method	URL
PUT	https://api.opsgenie.com/v2/roles/:identifier

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

HTTP Method	URL
DELETE	https://api.opsgenie.com/v2/roles/:identifier

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
GET	https://api.opsgenie.com/v2/roles

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