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

​

Fields of RoleAssignmentWrapper
role_assignments array of RoleAssignmentResponse

​

Fields of RoleAssignmentResponse
role Role

​

Values of Role
ROLE_UNSPECIFIED

Default value, should not be used.

ROLE_OWNER

​

user_rid string

​

Request

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)

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

{
  "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

​

Fields of RoleAssignmentResponse
role Role

​

Values of Role
ROLE_UNSPECIFIED

Default value, should not be used.

ROLE_OWNER

​

user_rid string

​

Request

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)

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

{
  "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

​

Fields of RoleAssignmentRequest
role Role

​

Values of Role
ROLE_UNSPECIFIED

Default value, should not be used.

ROLE_OWNER

​

user_rid string

​

assignments_to_remove array of RoleAssignmentRequest

​

Response: UpdateResourceRolesResponse

A message with no fields.

Request

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)

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

{}

Types#

Role#

ROLE_UNSPECIFIED

Default value, should not be used.

ROLE_OWNER

​

RoleAssignmentRequest#

role Role

​

user_rid string

​

RoleAssignmentResponse#

role Role

​

user_rid string

​

RoleAssignmentWrapper#

role_assignments array of RoleAssignmentResponse

​

Page design based on Scalar, MIT License.