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

JSON Body Fields

FieldsMandatoryDescription
nametrueName of the defined custom user role
extendedRolefalseDefault user role which is extended. Possible values are
user, observer and stakeholder. Default value is user
grantedRightsfalseYou can refer User Right Prerequisites for detailed information about possible values of rights.
disallowedRightsfalseYou 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 NameDescription
identifierIdentifier of the custom user role

Query Parameters

ParameterMandatoryDescription
identifierTypefalseType 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 NameDescription
identifierIdentifier of the custom user role

Query Parameters

ParameterMandatoryDescription
identifierTypefalseType 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

FieldsMandatoryDescription
namefalseName of the defined custom user role
extendedRolefalseDefault user role which is extended. Possible values are
user, observer and stakeholder. Default value is user
grantedRightsfalseYou can refer User Right Prerequisites for detailed information about possible values of rights.
disallowedRightsfalseYou 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 NameDescription
identifierIdentifier of the custom user role

Query Parameters

ParameterMandatoryDescription
identifierTypefalseType 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.

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.

RightPrerequisiteRequired 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-editprofile-edituser
configurations-read-onlywho-is-on-call-show-all, alerts-access-all, contacts-edituser
configurations-editconfigurations-read-onlyuser
configurations-deleteconfigurations-edituser
billing-manageconfigurations-edituser
alert-action-user
alert-createalert-actionuser
alert-add-attachmentalert-actionuser
alert-delete-attachmentalert-actionuser
alert-add-notealert-actionuser
alert-acknowledgealert-actionuser
alert-unacknowledgealert-actionuser
alert-snoozealert-actionuser
alert-escalatealert-actionuser
alert-closealert-actionuser
alert-deletealert-closeuser
alert-take-ownershipalert-actionuser
alert-assign-ownershipalert-actionuser
alert-add-recipientalert-actionuser
alert-add-teamalert-actionuser
alert-edit-tagsalert-actionuser
alert-edit-detailsalert-actionuser
alert-custom-actionalert-actionuser
alert-update-priorityalert-actionuser
alert-acknowledge-allalert-acknowledgeuser
alert-close-allalert-closeuser
incident-createalert-createuser
incident-add-stakeholderalert-add-recipientuser
incident-add-responderalert-add-recipientuser
incident-resolvealert-actionuser
incident-reopenalert-actionuser
mass-notification-createalert-actionuser
service-access-status-observer, stakeholder, user