Roles

Resource URI

/roles

Items in curly braces represent variables.

Description

Roles control access to and visibility of APIs and Package Plans in the Portal. The Mashery v3 API supports fetching roles. Please consult the V2 API documentation for creating, updating and deleting roles.

Note: With the adoption of DAPI (Distributed API Management), we have re-branded "Roles" as "Portal Access Groups".  We have updated our documentation to reflect this name change, however the resource names in the URI (V3 API) and method names (V2 API) have not been updated to reflect this change. For example, you will still use the URI path of "/roles" will be used in a V3 API call that is accessing Portal Access Group objects.

Resource Schema

Property	Characteristics
id	Type	string
	Sub-type
	Create Rule	Ignored
	Update Rule	Required (if not in context)
	Fetch Rule	Implicit
	Description	Object identifier.
created	Type	string
	Sub-type	datetime
	Create Rule	Ignored
	Update Rule	Ignored
	Fetch Rule	Implicit
	Description	Date/time the object was created.
updated	Type	string
	Sub-type	datetime
	Create Rule	Ignored
	Update Rule	Ignored
	Fetch Rule	Implicit
	Description	Date/time the object was updated.
name	Type	string
	Sub-type
	Create Rule	Required
	Update Rule	Optional
	Fetch Rule	Implicit
	Description	Role name.
group	Type	object
	Sub-type	Organization
	Create Rule	Optional
	Update Rule	Optional
	Fetch Rule	Explicit
	Description	Applications that belong to the Service.

fetch all [GET]

Retrieves collection of Roles belonging to the given Area

Parameters

Parameter	Required	Type	Description
fields	false	string	Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names. fields=<property\[.property...\]>\[,...\]\[&fields=...\]
filter	false	string	Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path. filter=<property\[.property...\]>:<value>\[&filter=...\]
sort	false	string	Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc). sort=<property\[:(asc\|desc)\]>\[,...\]\[&sort=...\]
limit	false	int	Number of objects to return in the result. Defaults to 100.
offset	false	int	0-based index of first object in the list to return. Defaults to 0 for /service and /packages APIs. For /members, /applications, /packageKeys, and /roles APIs, the offset field functions as a page index, where the first page is indexed as 0.

Returns

Success

Array of Roles for the Area If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "created": "2015-10-04T09:24:10.000+0000",
        "id": "c6d46ace-8b31-4184-9e84-ef9d453a0c9e",
        "name": "luctus ultricies eu nibh",
        "updated": "2015-01-09T05:31:56.000+0000"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "created": "2015-05-22T06:41:44.000+0000",
        "id": "6874eec8-285d-413b-8be3-3fcbe206fa5e",
        "name": "primis",
        "updated": "2015-03-27T09:25:50.000+0000"
    }
]

fetch [GET]

Retrieves the identified Role.

Parameters

Parameter	Required	Type	Description
roleId	true	string	Role identifier.
fields	false	string	Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names. fields=<property\[.property...\]>\[,...\]\[&fields=...\]
filter	false	string	Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path. filter=<property\[.property...\]>:<value>\[&filter=...\]
sort	false	string	Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc). sort=<property\[:(asc\|desc)\]>\[,...\]\[&sort=...\]
limit	false	int	Number of objects to return in the result. Defaults to 100.
offset	false	int	0-based index of first object in the list to return. Defaults to 0 for /service and /packages APIs. For /members, /applications, /packageKeys, and /roles APIs, the offset field functions as a page index, where the first page is indexed as 0.

Returns

Success

Array of ServiceDefinitions for the Area If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "created": "2015-04-23T06:17:26.000+0000",
        "id": "8f8c3c4f-682d-4030-9019-b67d12a19a2c",
        "name": "integer",
        "updated": "2015-08-17T13:36:34.000+0000"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "created": "2015-03-29T18:15:52.000+0000",
        "id": "07093c3c-9fe5-46ce-8de8-2f93f1ea68d1",
        "name": "libero nullam sit amet",
        "updated": "2015-04-07T10:47:41.000+0000"
    }
]

create [POST]

Creates a new Role in the given Area.

Parameters

Parameter	Required	Type	Description
role	true	object	Role object

Returns

Success

ServiceDefinition as created If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request POST --data '{"created":"2015-12-07T03:56:11.000+0000","id":"e289739c-9407-4607-9ce9-a00ac7d5fa84","name":"eget semper rutrum nulla","updated":"2015-03-10T08:41:23.000+0000"}

Response

[
    {
        "created": "2015-10-08T13:01:51.000+0000",
        "id": "22d74bb5-869a-42b9-bcd9-188e49aa55c6",
        "name": "orci",
        "updated": "2015-09-11T22:19:53.000+0000"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request POST --data '{"created":"2015-12-08T06:52:09.000+0000","id":"5f63f549-075b-4ffa-b092-0375d6f0b41d","name":"tincidunt in leo maecenas","updated":"2015-12-23T19:54:24.000+0000"}

Response

[
    {
        "created": "2015-06-09T19:22:21.000+0000",
        "id": "deee5037-c921-481a-b9a6-b16fcc2081a7",
        "name": "sit",
        "updated": "2015-03-06T23:46:41.000+0000"
    }
]

update [PUT]

Updates the identified Role.

Parameters

Parameter	Required	Type	Description
roleId	true	string	Role identifier.
role	true	object	Role object

Returns

Success

ServiceDefinition as persisted If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"created":"2015-12-13T19:36:33.000+0000","id":"59dcf06a-82f9-4962-a775-5cd8a2cf7a3f","name":"rhoncus aliquam lacus morbi","updated":"2015-08-25T13:49:16.000+0000"}

Response

[
    {
        "created": "2015-07-04T01:14:00.000+0000",
        "id": "8a3f2cab-d907-4bbd-b497-ccf59f64df0f",
        "name": "quis odio consequat",
        "updated": "2015-09-23T09:58:51.000+0000"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"created":"2015-08-11T09:59:07.000+0000","id":"0a84eabe-0444-49f5-898d-7e0555914c9e","name":"curabitur convallis duis","updated":"2015-05-13T13:21:13.000+0000"}

Response

[
    {
        "created": "2015-03-10T12:20:14.000+0000",
        "id": "01b28a09-6295-4c4c-a759-5e37b9e4226c",
        "name": "metus arcu",
        "updated": "2015-12-05T16:25:01.000+0000"
    }
]

delete [DELETE]

Deletes the identified Role.

Parameters

Parameter	Required	Type	Description
roleId	true	string	Role identifier.

Returns

Success

Empty response

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request DELETE

Response

[
    ""
]

Request

curl -k 'https://api.mashery.com/v3/rest/roles/{roleId}' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request DELETE

Response

[
    ""
]

 

How to create/update a Portal Access Group for an Organization

Request URL: POST /roles

{{{"name":"newGroup","organization":{"id":" {id} ","name":"","updated":"","created":"","description":"","parent":null,"suborganizations":[]}}}}

Example

Request URL:  POST /roles

{
  "name": "newGroup",
  "organization": {
    "id": "{id}",
    "name": "",
    "updated": "",
    "created": "",
    "description": "",
    "parent": null,
    "suborganizations": []
  }
}

Example

Request:

{
  "name": "test_pag",
  "organization": {
    "id": "ba4a004e-7476-42bb-b1ec-dbf8d847449d",
    "name": "",
    "updated": "",
    "created": "",
    "description": "",
    "parent": null,
    "suborganizations": []
  }
}

Response:

{
  "id": "bf6fc326-350e-4b36-906f-ea08ecbeb9e1",
  "created": "2022-04-21T10:20:59Z",
  "updated": "2022-04-21T10:20:59Z",
  "name": "test_pag",
  "description": "",
  "isPredefined": false,
  "isOrgrole": false,
  "isAssignable": true
}

How to Manage Roles using Mashery V2/V3 API

The Roles endpoint is the recommended way to interact with roles via API.

The field group is an object type that defines applications that belong to the Service. A sub-type of Organization exists. Create Rule and Update Rule are optional. Fetch Rule is explicit.

For more information on management of default roles, see Roles.

How to Retrieve the Organization that the Role Belongs to

GET /v3/roles

Example

Request: GET /roles/?fields=id,name,created,updated,organization'

Response:

How to Create a Role for a Specific Organization

{ "name": "newGroup", "organization": {   "id": "{id}",    "name": "",    "updated": "",    "created": "",    "description": "",    "parent": null,    "suborganizations": []  }}

Example:

Request URL : POST /roles

Request:

Response: