cloudfoundry/cloud_controller_ng

### Create a role

```
Example Request (by user guid)
```

```shell
curl "https://api.example.org/v3/roles" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
      "type": "organization_auditor",
      "relationships": {
        "user": {
          "data": {
            "guid": "user-guid"
          }
        },
        "organization": {
          "data": {
            "guid": "org-guid"
          }
        }
      }
    }'
```

```
Example Response
```

```http
HTTP/1.1 201 Created
Content-Type: application/json

<%= yield_content :single_role %>
```

```
Example Request (by username and origin)
```

```shell
curl "https://api.example.org/v3/roles" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
      "type": "organization_auditor",
      "relationships": {
        "user": {
          "data": {
            "username": "user-name",
            "origin": "ldap"
          }
        },
        "organization": {
          "data": {
            "guid": "org-guid"
          }
        }
      }
    }'
```

```
Example Response
```

```http
HTTP/1.1 201 Created
Content-Type: application/json

<%= yield_content :single_role %>
```

This endpoint creates a new role for a user in an organization or space.

To create an organization role you must be an admin or organization manager in the organization associated with the role.

To create a space role you must be an admin, an organization manager in the parent organization of the space associated with the role, or a space manager in the space associated with the role.

For a user to be assigned a space role, the user must already have an organization role in the parent organization.

If the associated user is valid but does not exist in Cloud Controller's database, a user resource will be created automatically.

#### Definition
`POST /v3/roles`

#### Required parameters

Name | Type | Description
---- | ---- | -----------
**type** | _string_ | Role to create; see [valid role types](#valid-role-types)
**relationships.user** | [_to-one relationship_](#to-one-relationships) | A relationship to a user; the user can be defined by either a `guid` or, if the `set_roles_by_username` [feature_flag](#list-of-feature-flags) is enabled, a `username` (with the option of including an `origin` to disambiguate it)
**relationships.organization** | [_to-one relationship_](#to-one-relationships) | A relationship to an organization; required only when creating an organization role
**relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to a space; required only when creating a space role

#### Permitted roles

Role | Notes
--- | ---
Admin |
Org Manager | Can create roles in managed organizations and spaces within those organizations; can also create roles for users outside of managed organizations when `set_roles_by_username` [feature_flag](#list-of-feature-flags) is enabled; this requires identifying users by username and origin
Space Manager | Can create roles in managed spaces for users in their org