# Role service (gRPC)

RoleService provides methods for managing roles within Nominal.

## Endpoints

### Batch get resource roles

gRPC `/nominal.authorization.roles.v1.RoleService/BatchGetResourceRoles`

Gets the role assignments for multiple resources.

Request: `BatchGetResourceRolesRequest`

`resources` array of string
:   ​

Response: `BatchGetResourceRolesResponse`

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

    Fields of `RoleAssignmentWrapper`

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

        Fields of `RoleAssignmentResponse`

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

            Values of `Role`

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

            `ROLE_OWNER`
            :   ​

        `user_rid` string
        :   ​

Request

**Python**

```python
import grpc
from nominal.protos.authorization.roles.v1 import roles_pb2, roles_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
role_service = roles_pb2_grpc.RoleServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = roles_pb2.BatchGetResourceRolesRequest(resources=["<resources>"])
response = role_service.BatchGetResourceRoles(request, metadata=auth)
print(response)
```

**Go**

```go
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	rolesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/roles/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	roleService := rolesv1.NewRoleServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &rolesv1.BatchGetResourceRolesRequest{
		Resources: []string{
			"<resources>",
		},
	}
	response, err := roleService.BatchGetResourceRoles(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

Response

```json
{
  "role_assignments_by_resource": {
    "<key>": {
      "role_assignments": [
        {
          "role": "ROLE_OWNER",
          "user_rid": "<user rid>"
        }
      ]
    }
  }
}
```

### Get resource roles

gRPC `/nominal.authorization.roles.v1.RoleService/GetResourceRoles`

Gets the role assignments for a resource.

Request: `GetResourceRolesRequest`

`resource` string
:   ​

Response: `GetResourceRolesResponse`

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

    Fields of `RoleAssignmentResponse`

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

        Values of `Role`

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

        `ROLE_OWNER`
        :   ​

    `user_rid` string
    :   ​

Request

**Python**

```python
import grpc
from nominal.protos.authorization.roles.v1 import roles_pb2, roles_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
role_service = roles_pb2_grpc.RoleServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = roles_pb2.GetResourceRolesRequest(resource="<resource>")
response = role_service.GetResourceRoles(request, metadata=auth)
print(response)
```

**Go**

```go
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	rolesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/roles/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	roleService := rolesv1.NewRoleServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &rolesv1.GetResourceRolesRequest{
		Resource: "<resource>",
	}
	response, err := roleService.GetResourceRoles(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

Response

```json
{
  "role_assignments": [
    {
      "role": "ROLE_OWNER",
      "user_rid": "<user rid>"
    }
  ]
}
```

### Update resource roles

gRPC `/nominal.authorization.roles.v1.RoleService/UpdateResourceRoles`

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

Request: `UpdateResourceRolesRequest`

`resource` string
:   ​

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

    Fields of `RoleAssignmentRequest`

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

        Values of `Role`

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

        `ROLE_OWNER`
        :   ​

    `user_rid` string
    :   ​

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

Response: `UpdateResourceRolesResponse`

A message with no fields.

Request

**Python**

```python
import grpc
from nominal.protos.authorization.roles.v1 import roles_pb2, roles_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
role_service = roles_pb2_grpc.RoleServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = roles_pb2.UpdateResourceRolesRequest(
    resource="<resource>",
    assignments_to_add=[{"role": "ROLE_OWNER", "user_rid": "<user rid>"}],
    assignments_to_remove=[{"role": "ROLE_OWNER", "user_rid": "<user rid>"}],
)
response = role_service.UpdateResourceRoles(request, metadata=auth)
print(response)
```

**Go**

```go
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	rolesv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authorization/roles/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	roleService := rolesv1.NewRoleServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &rolesv1.UpdateResourceRolesRequest{
		Resource: "<resource>",
		AssignmentsToAdd: []*rolesv1.RoleAssignmentRequest{
			{
				Role:     rolesv1.Role_ROLE_OWNER,
				Assignee: &rolesv1.RoleAssignmentRequest_UserRid{UserRid: "<user rid>"},
			},
		},
		AssignmentsToRemove: []*rolesv1.RoleAssignmentRequest{
			{
				Role:     rolesv1.Role_ROLE_OWNER,
				Assignee: &rolesv1.RoleAssignmentRequest_UserRid{UserRid: "<user rid>"},
			},
		},
	}
	response, err := roleService.UpdateResourceRoles(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

Response

```json
{}
```

## Types

### Role

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

`ROLE_OWNER`
:   ​

### RoleAssignmentRequest

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

`user_rid` string
:   ​

### RoleAssignmentResponse

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

`user_rid` string
:   ​

### RoleAssignmentWrapper

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

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