You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/system-administration/apigee-roles). info

This topic discusses how to create custom roles and assign roles to users through the
management API. We also show how to test role assignments through the API. (For an overview of
custom roles, see [Creating custom roles in the
UI](https://docs.apigee.com/api-platform/system-administration/creating-custom-roles).)

## About permission setting

Role permissions are set on management API URIs (not management UI URIs). For example, if you
want to set PUT, GET, and/or DELETE permissions on the app developer entities in your Edge
organization, you'd set permissions on the `/developers` resource, because the
management API path for [developers](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/developers) is
`https://api.enterprise.apigee.com/v1/organizations/{org_name}/developers`.
(You don't need to include the organization part of the path when defining permissions, because
permissions are scoped to a specific organization, as the management API calls in this topic
illustrate.)

You can also set permissions on specific entities. For example:

- If you wanted to set permissions on a single developer, set them on `/developers/steve@example.com`
- For a specific API product, such as free-api-product, set them on `/apiproducts/free-api-product`
- For a key value map in a specific environment, you'd set permission on something like `/environments/test/keyvaluemaps/fooMap`, or `/environments/test/keyvaluemaps/*` for all key value maps in the test environment.

> [!NOTE]
> **Note:** Names of entities, such as API products, apps, etc. should not contain spaces.

The permissions you set using the API:

- Allow users in a custom role to make [management API
  calls](https://docs.apigee.com/management/apis) according to their permissions. For example, if a role allows read-only access to all API proxies, a user in that role could use the [List API Proxies](https://docs.apigee.com/management/apis/get/organizations/{org_name}/apis) API but not the [Create an API Proxy](https://docs.apigee.com/management/apis/post/organizations/{org_name}/apis) API.
- Determine what users in a custom role can see and do in the management UI. For example, read-only access to API proxies disables access to the +API Proxy and Delete buttons on the API Proxies page.

To see the resources and paths that you can set permissions on, look through the [management API reference](https://docs.apigee.com/management/apis) at the different resource URLs.

See the [User roles](https://docs.apigee.com/api/user-roles) API for complete reference information on
role management.

### Syntax and precedence

You can use the asterisk wild card (\*) to indicate "everything after" in a permission setting.
However, if you set permissions only on a parent resource (such as on /developers) without
setting any more specific permissions (such as /developers/\*), the permission applies to
everything from /developers and after.

PUT also serves as POST in permissions.

You can mix general with more granular permissions on resources. The more granular settings
take precedence where there is a permissions overlap. For example, assume the following
permissions are set on a "developeradmin" role:

- PUT on /developers
- GET on /developers/\*

This means the developeradmin can:

- Create a developer, but not update any specific developers or any sub-entities (because of the more specific GET permission on that path).
- Get any developer or sub-entity, but not get a list of all developers.

See [Permissions reference](https://docs.apigee.com/api-platform/system-administration/permissions) for a complete list of permissions that you can set with the API.

## Create a new custom role called "development"

Create a 'development' role to enable developers to view, create, and update API proxies.

```
$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/userroles -H "Content-type:application/json" -X POST -d'{ "role" : [ { "name" : "development" } ] }'
```

## Add permissions to the development role

The permissions that can be set on an entire group of Edge artifacts (such as all /apps,
/apis, /apiproducts, and so on) as well as on individual artifacts (such as a specific app, API
proxy, or API product) are GET, PUT, and DELETE.

GET enables users to view any APIs, including API proxy configuration files, associated
policies, JavaScript, XSLT files, and so on. The PUT permission on APIs enables developers to
create, modify, import, export, deploy and undeploy API proxies.

The path attribute specifies the artifact on which you set the permissions. For example,
/applications, /apps, /apiproducts, /developers, or /reports.

```
curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/userroles/development/permissions -H "Content-type:application/json" -X POST -d'{"path" : "/applications","permissions" : [ "put", "get" ]}'
```

> [!NOTE]
> **Note:** The role resource path for all proxies is /applications and for a specific API proxy it is `/applications/<proxy_name>`.

## Create a role: testing

Create a 'testing' role to enable quality engineers to view API proxies and their contents
(including, for example, policies).

```
$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/userroles -H "Content-type:application/json" -X POST -d'{ "role" : [ { "name" : "testing" } ] }'
```

## Add permissions to testing role

GET enables users to view any APIs, including their configuration files, as well as any
associated policies, JavaScript, XSLT files, and so on. By adding this permission to the
'testing' role, we enable quality engineers to view the contents of the APIs that they are
testing. Users in this role will not, however, be able to create, modify, import, export, deploy
and undeploy API proxies.

```
$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/userroles/testing/permissions -H "Content-type:application/json" -X POST -d'{"path" : "/applications","permissions" : [ "get" ]}'
```

For an on-premises installation of Edge, the minimum set of permissions that have to be set to
allow the user to log in to the Edge UI are:

```
{"path" : "/","permissions" : [ "get" ]}
{"path" : "/*","permissions" : [ ]}
{"path" : "/environments","permissions" : [ "get" ]}
{"path" : "/userroles","permissions" : [ "get" ]}
```

Use the following cURL command to set these permissions:

```
curl -H "Content-Type:application/json" -u email:password \
-X POST \
http://<ms-IP>:8080/v1/organizations/{org_name}/userroles/testing/resourcepermissions  \
-d '{
 "resourcePermission" : [ 
   {
    "path" : "/",
    "permissions" : [ "get" ]
   }, 
{
    "path" : "/*",
    "permissions" : []
   },
{
    "path" : "/environments",
    "permissions" : [ "get" ]
   },
   {
    "path" : "/userroles",
    "permissions" : [ "get"]
   }
  ]
}'
```

where *\<ms-IP\>*
is the IP address or DNS name of the Edge Management Server.

## Add user to testing role

To provision a user with a user role:

```
$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/users/justauser@apigee.com/userroles -H "Content-type:application/json" -X POST -d'{"role" : [ {"name" : "testing"} ] }'
```

## View APIs as user

Impersonate the user and make a request to API Services to view API proxies. The user should be able to view APIs, along with their contents.

```
$ curl -u justauser@apigee.com:secret https://api.enterprise.apigee.com/v1/o/{org_name}/apis
```

```
$ curl -u justauser@apigee.com:secret https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/policies
```

## Create API as user in testing role

Impersonate the user and make a request to API Services to create an API proxy. The request
will be rejected by API Services, as the role 'testing' does not permit the user to create
APIs.

```
$ curl -u justauser@apigee.com:secret -H "Content-Type: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis -X POST -d'{"name" : "rbacTestApi"}'
```

## Add user to development role

Now provision the user with the 'development' role.

```
$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/users/justauser@apigee.com/userroles -H "Content-type:application/json" -X POST -d'{"role" : [ {"name" : "development"} ] }'
```

## Create API as user in development role

Impersonate the user and repeat the request to the API Platform to create an API proxy. The
request will be successful, as the role 'development' does permit the user to create APIs.

```
$ curl -u justauser@apigee.com:secret -H "Content-Type: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis -X POST -d'{"name" : "rbacTestApi"}'
```

## Get user roles for a user

As an organization administrator, you can check the list of user roles for a user (across all
organizations) at any time:

```
$ curl -u email:password -X GET https://api.enterprise.apigee.com/v1/users/justauser@apigee.com/userroles
```