roles - cisco.com · roles...

Roles

This set of APIs can be used to manage user roles. They require that the user_role_scope_managementcapability be associated with the API key.

These APIs are only available to site admins and owners of root scopes.Note

• Role Object, on page 1• Get Roles, on page 1• Create A Role, on page 2• Get A Specific Role, on page 2• Update A Role, on page 3• Give A Role Access to A Scope, on page 3• Delete A Specific Role, on page 4

Role ObjectThe role object attributes are:

DescriptionTypeAttribute

Unique identifier for the role.stringid

Application for which the scope is defined, maybeempty for “Service Provider Roles.”

stringapp_scope_id

User-specified name for the role.stringname

User-specified description for the role.stringdescription

Get RolesThis endpoint returns a list of roles accessible to the current user. Roles can be filtered to a given root scope.If no scope is provided, all roles, for all scopes the user has access to, are returned. Service provider roles willonly be returned if the user is a site admin.

Roles1

GET /openapi/v1/roles

Parameters:

DescriptionTypeName

(Optional) ID of a root scope, to return roles onlyassigned to that scope.

stringapp_scope_id

Response object: Returns a list of user role objects.

Sample Python code

resp = restclient.get('/roles')

Create A RoleThis endpoint is used to create a new role.POST /openapi/v1/roles

Parameters:

DescriptionTypeName

User-specified name for the role.stringname

User-specified description for therole.

stringdescription

(Optional) The scope ID underwhich the role is created. If noscope ID is provided, the role isconsidered to be a Service Providerrole.

stringapp_scope_id

The requesting user must have access to the provided scope. A role without a scope is called a ‘Service ProviderRole’ and only site admins may create them.

Response object: Returns the newly created role object.

Sample Python code

app_scope_id = '<app-scope-id>'req_payload = {

'name': 'Role Name','description': 'Role Description','app_scope_id': app_scope_id

}restclient.post('/roles', json_body=json.dumps(req_payload))

Get A Specific RoleThis endpoint returns a specific role object.

Roles2

RolesCreate A Role

GET /openapi/v1/roles/{role_id}

Parameters: The request URL contains the following parameters:

DescriptionTypeName

Unique identifier for the role.stringrole_id

Response object: Returns the role object associated with the specified ID.

Sample Python code

role_id = '<role-id>'restclient.get('/roles/%s' % role_id)

Update A RoleThis endpoint is used to update an existing role.PUT /openapi/v1/roles/{role_id}

Parameters: The request URL contains the following parameters:

DescriptionTypeName

Unique identifier for the role.stringrole_id

The JSON request body contains the following parameters:

DescriptionTypeName

User-specified name for the role.stringrole

User-specified description for the role.stringdescription

The requesting user must have access to the provided scope. A role without a scope is called a “ServiceProvider Role” and only site admins may update those roles.

Response object: The updated role object with the specified ID.

Sample Python code

role_id = '<role-id>'req_payload = {

'name': 'Role Name','description': 'Role Description',

}restclient.put('/roles/%s' % role_id, json_body=json.dumps(req_payload))

Give A Role Access to A ScopeThis endpoint gives a role a specific level of access to a scope.POST /openapi/v1/roles/{role_id}/capabilities

Roles3

RolesUpdate A Role

Capabilities can only be added to the roles to which a user has access. If the role is assigned to a scope,capabilities must correspond to that scope or its children. Service Provider roles (those not assigned to a scope)can add capabilities for any scope.

Parameters: The request URL contains the following parameters:

DescriptionTypeName

Unique identifier for the role.stringrole_id

The JSON request body contains the following parameters:

DescriptionTypeName

ID of the scope to which access is provided.stringapp_scope_id

Possible values are SCOPE_READ, SCOPE_WRITE,EXECUTE, ENFORCE, SCOPE_OWNER, DEVELOPER.

stringability

Response object:

DescriptionTypeName

ID of the scope to which access is provided.stringapp_scope_id

ID of the role.stringrole_id

Possible values are SCOPE_READ, SCOPE_WRITE,EXECUTE, ENFORCE, SCOPE_OWNER, DEVELOPER.

stringability

booleaninherited

Sample Python code

role_id = '<role-id>'req_payload = {

'app_scope_id': '<app-scope-id>','ability': 'SCOPE_READ'

}restclient.post('/roles/%s/capabilities' % role_id,

json_body=json.dumps(req_payload))

Delete A Specific RoleThis endpoint deletes the specified role.DELETE /openapi/v1/roles/{role_id}

Parameters: The request URL contains the following parameters:

DescriptionTypeName

Unique identifier for the role.stringrole_id

Response object: None.

Roles4

RolesDelete A Specific Role

Sample Python code

role_id = '<role-id>'restclient.delete('/roles/%s' % role_id)

Roles5

RolesDelete A Specific Role

Roles6

RolesDelete A Specific Role