Roles

The Roles resource provide methods to read and write roles as well as associate permissions to roles.

Get

This method allows client applications to retrieve a list of roles based on a grain, securableItem and optionally a role name. This is not a user specific endpoint and will return all roles for that grain/securableItem/{permissionName} combination regardless of user.

GET /roles/{grain}/{securableItem}
GET /roles/{grain}/{securableItem}/{roleName}

Parameters

Name	Location	Type	Description
grain	path	string	The top level grain to return roles for
securableItem	path	string	the specific securableItem within the grain to return roles for
roleName	path	string	the name of the role

Authorization

This request requires authorization with the following scopes:

• fabric/authorization.read

Request Body

Do not supply a request body with this method

Responses

200

[
  {
    "id": guid,
    "grain": string,
    "securableItem": string,
    "name": string,
    "permissions": [
      {
        "id": guid,
        "grain": string,
        "securableItem": string,
        "name": string
      }
    ]
  }
]

403 Forbidden

A Forbidden response will be returned in the following cases:

• If the requested grain/securableItem does not match the clientid presented
• If the access token can not be validated (i.e. is forged or doesn't have the correct scope)

Post

This method allows clients to add roles to the Authorization service store.

POST /roles/

Parameters

Name	Location	Type	Description
None	N/A	N/A	N/A

Authorization

This request requires authorization with the following scopes:

• fabric/authorization.write

Request Body

{
	"grain": string,
	"securableItem": string,
	"name": string
}

Responses

201

A 201 created response will be returned if the role is successfully created.

400

A 400 Bad Request will be returned in the following cases:

• If the request is malformed
• If the role already exists

403 Forbidden

A Forbidden response will be returned in the following cases:

• If the requested grain/securableItem does not match the clientid presented
• If the access token can not be validated (i.e. is forged or doesn't have the correct scope)

Post

This method allows clients to add permissions to roles that exist in the Authorization service store.

POST /roles/{roleId}/permissions

Parameters

Name	Location	Type	Description
roleId	path	guid	The unique identifier for the role to add the permissions to

Authorization

This request requires authorization with the following scopes:

• fabric/authorization.write

Request Body

[
  {
    "id": guid,
    "grain": string,
    "securableItem": string,
    "name": string
  }
]

Responses

204

A 204 No Content response will be returned if the permissions are added to the role successfully.

400

A 400 Bad Request will be returned in the following cases:

• If the request is malformed
• If the role doesn't exist
• If the permission already exists on the role

403 Forbidden

A Forbidden response will be returned in the following cases:

• If the requested grain/securableItem does not match the clientid presented
• If the access token can not be validated (i.e. is forged or doesn't have the correct scope)

Delete

DELETE /roles/{roleId}

Parameters

Name	Location	Type	Description
roleId	path	guid	The unique identifier for the role to delete

Authorization

This request requires authorization with the following scopes:

• fabric/authorization.write

Request Body

Do not supply a request body with this method

Responses

204

A 204 no content response will be returned if the role is successfully deleted.

400

A 400 Bad Request respons will be returned in the following cases:

• The role being deleted does not exist in the Authorization service data store
• The request is malformed

403 Forbidden

A Forbidden response will be returned in the following cases:

• If the requested grain/securableItem does not match the clientid presented
• If the access token can not be validated (i.e. is forged or doesn't have the correct scope)

Delete

This method allows clients to delete permissions from a role that exist in the Authorization service store.

DELETE /roles/{roleId}/permissions

Parameters

Name	Location	Type	Description
roleId	path	guid	The unique identifier for the role to delete the permissions from

Authorization

This request requires authorization with the following scopes:

• fabric/authorization.write

Request Body

[
  {
    "id": guid,
    "grain": string,
    "securableItem": string,
    "name": string
  }
]

Responses

204

A 204 No Content response will be returned if the permissions are deleted from the role successfully.

400

A 400 Bad Request will be returned in the following cases:

• If the request is malformed
• If the role doesn't exist
• If the permission and role grain/securableItem combination don't match
• If the permission doesn't exist on the role

403 Forbidden

A Forbidden response will be returned in the following cases:

• If the requested grain/securableItem does not match the clientid presented
• If the access token can not be validated (i.e. is forged or doesn't have the correct scope)