# Role service

RoleService provides methods for managing roles within Nominal.

OpenAPI file: [`nominal.authorization.roles.v1.json`](https://dev.nominal.io/api/_downloads/d93b5e334ef4784e10c3b1d71de0de00/nominal.authorization.roles.v1.json)

## Endpoints

### Batch get resource roles

POST `/authorization/roles/v1/batch-get-resource-roles`

Gets the role assignments for multiple resources.

Body

`resources` array of string
:   ​

Response

`roleAssignmentsByResource` map of string to [`RoleAssignmentWrapper`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentwrapper)
:   ​

    Fields of `RoleAssignmentWrapper`

    `roleAssignments` array of [`RoleAssignmentResponse`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentresponse)
    :   ​

        Fields of `RoleAssignmentResponse`

        `role` [`Role`](https://dev.nominal.io/api/rest/role-service.md#role)
        :   ​

            Values of `Role`

            `ROLE_UNSPECIFIED`
            :   Default value, should not be used.

            `ROLE_OWNER`
            :   ​

        `userRid` string
        :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/roles/v1/batch-get-resource-roles" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resources": [
    "<resources>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/roles/v1/batch-get-resource-roles",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/roles/v1/batch-get-resource-roles",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/roles/v1/batch-get-resource-roles",
            headers={"Authorization": "Bearer <api key>"},
            json={"resources": ["<resources>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "roleAssignmentsByResource": {
    "<key>": {
      "roleAssignments": [
        {
          "role": "ROLE_OWNER",
          "userRid": "<user rid>"
        }
      ]
    }
  }
}
```

### Get resource roles

GET `/authorization/roles/v1/resource/{resource}/roles`

Gets the role assignments for a resource.

Path parameters

`resource` string required
:   ​

Response

`roleAssignments` array of [`RoleAssignmentResponse`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentresponse)
:   ​

    Fields of `RoleAssignmentResponse`

    `role` [`Role`](https://dev.nominal.io/api/rest/role-service.md#role)
    :   ​

        Values of `Role`

        `ROLE_UNSPECIFIED`
        :   Default value, should not be used.

        `ROLE_OWNER`
        :   ​

    `userRid` string
    :   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "roleAssignments": [
    {
      "role": "ROLE_OWNER",
      "userRid": "<user rid>"
    }
  ]
}
```

### Update resource roles

POST `/authorization/roles/v1/resource/{resource}/roles`

Atomically adds and removes role assignments for a resource. Throws if the same role assignment is both added and removed in the same request.

Path parameters

`resource` string required
:   ​

Body

`assignmentsToAdd` array of [`RoleAssignmentRequest`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentrequest)
:   ​

    Fields of `RoleAssignmentRequest`

    `role` [`Role`](https://dev.nominal.io/api/rest/role-service.md#role)
    :   ​

        Values of `Role`

        `ROLE_UNSPECIFIED`
        :   Default value, should not be used.

        `ROLE_OWNER`
        :   ​

    `userRid` string
    :   ​

`assignmentsToRemove` array of [`RoleAssignmentRequest`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentrequest)
:   ​

Response

An empty JSON object, `{}`.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "assignmentsToAdd": [
    {
      "role": "ROLE_OWNER",
      "userRid": "<user rid>"
    }
  ],
  "assignmentsToRemove": [
    {
      "role": "ROLE_OWNER",
      "userRid": "<user rid>"
    }
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "assignmentsToAdd": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
        "assignmentsToRemove": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "assignmentsToAdd": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
        "assignmentsToRemove": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/roles/v1/resource/<resource>/roles",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "assignmentsToAdd": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
                "assignmentsToRemove": [{"role": "ROLE_OWNER", "userRid": "<user rid>"}],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{}
```

## Types

### Role

`ROLE_UNSPECIFIED`
:   Default value, should not be used.

`ROLE_OWNER`
:   ​

### RoleAssignmentRequest

`role` [`Role`](https://dev.nominal.io/api/rest/role-service.md#role)
:   ​

`userRid` string
:   ​

### RoleAssignmentResponse

`role` [`Role`](https://dev.nominal.io/api/rest/role-service.md#role)
:   ​

`userRid` string
:   ​

### RoleAssignmentWrapper

`roleAssignments` array of [`RoleAssignmentResponse`](https://dev.nominal.io/api/rest/role-service.md#roleassignmentresponse)
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.