# Authorization (RBAC)

{% hint style="info" %}
New API available on <https://alphauslabs.github.io/blueapidocs/#/Iam>.
{% endhint %}

For general information about RBAC, check out this [link](https://docs.mobingi.com/v/ur-en/#rbac).

The following endpoint is the base url for the APIs below.

```
https://service.alphaus.cloud/m/auth/rbac/
```

## List permissions

List all permissions supported by RBAC in all namespaces. For reference, supported permissions can be found [here](https://github.com/mobingi/rbac-permissions).

**Request**

```http
GET /permissions HTTP1.1
authorization: Bearer {token}
```

**Response**

```ruby
HTTP/1.1 200 OK

[
  {
    "namespace":"wave",
    "permissions":[
      "Admin",
      "ModifySettings",
      "..."
    ]
  },
  {
    "namespace":"ripple",
    "permissions":[
      "Admin"
    ]
  }
]
```

## Create role

During role creation, if your `permissions` list contains an `Admin` entry, all other entries will be discarded except `Admin`.

Roles are root user-level. That means all roles created by the root user, or any subuser that has permissions to create roles, are available to all subusers.

**Request**

```http
POST /roles HTTP1.1
authorization: Bearer {token}
content-type: application/json

{
  "name":"testrole",
  "namespace":"wave",
  "permissions":[
    "ModifySettings",
    "ViewSettings",
    ...
  ]
}
```

Role names should have at least 6 characters in length and 32 characters maximum. It should also be alphanumeric. Hyphens and underscores are allowed in between. The regular expression used for validation is below:

```
^[A-Za-z0-9][A-Za-z0-9_-]*[A-Za-z0-9]$
```

**Response**

```ruby
HTTP/1.1 200 OK

{
  "name":"testrole",
  "namespace":"wave",
  "permissions":[
    "ModifySettings",
    "ViewSettings",
    ...
  ]
}
```

## List roles

**Request**

```http
GET /roles?namespace={namespace} HTTP1.1
authorization: Bearer {token}
```

The `{namespace}` parameter is optional. If not provided, all roles will be returned.

**Response**

```ruby
HTTP/1.1 200 OK

[
  {
    "name": "testrole",
    "namespace": "wave",
    "permissions": [
      "ModifySettings",
      "ViewSettings",
      "ModifyAccountSettings"
    ]
  },
  {
    "name": "waveAdmin",
    "namespace": "wave",
    "permissions": [
      "Admin"
    ]
  },
  ...
]
```

## Update role

Update role. If role name is different, rename mapped role name.

**Request**

```http
PATCH /roles/{namespace}/{rolename} HTTP1.1
authorization: Bearer {token}
content-type: application/json

{
  "namespace":"wave",
  "permissions":[
    "ModifySettings",
    "ViewSettings",
    ...
  ]
}
```

**Response**

```ruby
HTTP/1.1 200 OK

{
  "name": "testrole",
  "namespace":"wave",
  "permissions":[
    "ModifySettings",
    "ViewSettings",
    ...
  ]
}
```

## Delete role

Delete role. Deleting a role will also remove all mappings.

**Request**

```http
DELETE /roles/{namespace}/{rolename} HTTP1.1
authorization: Bearer {token}
```

## Map roles to user

You can only map (or attach) up to 5 roles to a user per namespace. There is no limit for filtering rules per user.

Valid values for `type` for filtering rules:

| Namespace | Value                       |
| --------- | --------------------------- |
| `wave`    | `linkAcct`, `group`, `tags` |
| `ripple`  | `billingGroup`              |

**Request**

```http
POST /userroles HTTP1.1
authorization: Bearer {token}
content-type: application/json

{
  "user_id":"subuser1",
  "roles":[
    {
      "namespace":"wave",
      "role": "somerole",
    },
    ...
    ]
}
```

**Response**

```ruby
HTTP/1.1 200 OK

{
  "success":[
    "somerole"
  ],
  "failed":[],
  "filters":[]
}
```

## List user role mappings

**Request**

For this endpoint, the returned role mappings are those attached to the caller.

```http
GET /userroles HTTP1.1
authorization: Bearer {token}
```

For listing role mappings of other subusers, use this endpoint.

```http
GET /{subuser}/userroles HTTP1.1
Authorization: Bearer {token}
```

`{subuser}` is the subuser name.

**Response**

```ruby
HTTP/1.1 200 OK

[
  {
    "root_user":"58c2297d25645",
    "sub_user":"subuser01",
    "namespace":"wave",
    "role":"testrole1"
  },
  {
    "root_user":"58c2297d25645",
    "sub_user":"subuser02",
    "namespace":"wave",
    "filter":"billingGroup:2222"
  },
  ...
]
```

## List user permissions

Retrieve all permissions to all roles attached to the `{subuser}`.

**Request**

```http
GET /{subuser}/permissions HTTP1.1
authorization: Bearer {token}
```

**Response**

```ruby
HTTP/1.1 200 OK

[
  {
    "namespace":"wave",
    "permissions":[
      "Admin",
      "ModifySettings",
      "..."
    ]
  },
  {
    "namespace":"ripple",
    "permissions":[
      "Admin"
    ]
  }
]
```

## Update map roles to user

You can only update map (or attach) up to 5 roles to a user per namespace. There is no limit for filtering rules per user.

Valid values for `type` for filtering rules:

| Namespace | Value                       |
| --------- | --------------------------- |
| `wave`    | `linkAcct`, `group`, `tags` |
| `ripple`  | `billingGroup`              |

This method replaces subuser's all roles to information in the request body.

**Request**

```http
PATCH /userroles HTTP1.1
authorization: Bearer {token}
content-type: application/json

{
  "roles":[
    {
      "namespace":"wave",
      "role": "somerole",
    },
    ...
    ]
}
```

```http
PATCH /{subuser}/userroles HTTP1.1
authorization: Bearer {token}
content-type: application/json

{
  "roles":[
    {
      "namespace":"wave",
      "role": "somerole",
    },
    ...
    ]
}
```

`{subuser}` is the subuser id.

**Response**

```ruby
HTTP/1.1 200 OK

{
  "success":[
    "somerole"
  ],
  "failed":[],
  "filters":[]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alphaus.cloud/api-reference/authorization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.