roles - cisco.com · roles...
TRANSCRIPT
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