Using the role commands

You can use the role commands to complete the full lifecycle of Drupal user roles. This includes creating and deleting of roles, as well as adding and removing permissions to the roles in your Developer Portal service.

Log in as Provider org as seen in the following example.
```
apic login --server management_server --realm provider/identity_provider --username provider_username --password provider_password
```
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
For full details of the apic login command, see Logging in to a management server.

For a summary of the general-purpose commands and their use, see Developer Portal CLI commands.
Get the details of a specific Drupal user role and all of the permissions granted to the role.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:get role
```
- mode is the toolkit operation mode.
- management_server is the endpoint URL of the management server (required).
- catalogid/name is the ID or name of the catalog that the site belongs to (required).
- orgid/name is the ID or name of the provider organization that the catalog belongs to (required).
- role is the name or label of the Drupal user role (required).
For example,
```
apic --mode portaladmin -server management-platform-api --org ibm --catalog api-connect-catalog-1 role:get portal_cli_blog
portal_cli_blog:
label: 'Portal CLI Blog'
perms:
  - 'access content'
  - 'access shortcuts'
```
The command returns the Drupal user role under the portal_cli_blog label as well as the permissions granted to the role.
List all of the Drupal user roles.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:list
```
List the Drupal user roles based on user permissions assigned to the role.
For example,
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:list --filter_by_permission=role_permission
```
- --filter_by_permission flag is used to filter the list based on specific permission (optional).
- role_permission is the permissions granted to a specific role.
List the Drupal user roles based on a specific role.
For example,
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:list --role=role
```
- --role flag is used to filter the list based on specific role (optional).

Create a new Drupal user role.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:create --machine_name machine_name --human_readable_name human_readable_name

Note: The command must include a machine_name and a human_readable_name.

The machine_name is used by Drupal to refer to the role and must contain only lowercase letters, numbers, and underscores.
The human_readable_name is displayed on the UI and can contain other characters such as spaces.

For example,

apic --mode portaladmin --server management-platform-api --org ibm --catalog api-connect-catalog-1 role:create --machine_name "portal_cli_blog" --human_readable_name "Portal CLI Blog"

Delete an unwanted Drupal user role.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:delete role

For example,

apic --mode portaladmin --server management-platform-api --org ibm --catalog api-connect-catalog-1 role:delete portal_cli_blog

If you try to delete a role that does not exist, you will get an error indicating that the specific user role doses not exist.

For example,

  - [error]  Unable to load the user_role: no_role

Add permissions to a Drupal user role using the permissions flag. You can add multiple permissions to a role using a comma separated list within a single command call.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:add-permission role --permissions=role_permissions

role_permissions is the permissions granted to a specific role (required).

For example,

apic --mode portaladmin --server management-platform-api --org ibm  --catalog api-connect-catalog-1 role:add-permission portal_cli_blog --permissions="access comments,access content,access shortcuts"

If you try to add permissions to a role that does not exist, you will get an error indicating that the permission is fake.

For example,

- [error]  Permission(s) not found: fake permission

Remove unwanted permissions from a Drupal user role using the permissions flag. You can delete multiple permissions from a role using a comma separated list within a single command call.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name role:remove-permission role --permissions=role_permissions

For example,

apic --mode portaladmin --server management-platform-api --org ibm --catalog api-connect-catalog-1 role:remove-permission portal_cli_blog --permissions="access comments"

If you try to remove permissions from a role that does not exist, you will get an error indicating that the permission does not exist.

For example,

 - [error]  Permission(s) not found: perm not on role