Group service (gRPC)#

Service for managing groups within an organization

Endpoints#

Create group membership#

gRPC /nominal.authentication.groups.v1.GroupService/CreateGroupMembership

Adds a member to a manually managed group. Re-adding an existing member is a no-op. Throws HTTP 400 / gRPC 3 if group_rid or member_rid is missing, or member_rid is not a supported RID type. Throws HTTP 403 / gRPC 7 if the caller is not authorized to update the group, including when the group does not exist. The permission check runs before the group lookup so unknown groups are not disclosed. Throws HTTP 400 / gRPC 3 if the target user is not in the group’s organization. Throws HTTP 400 / gRPC 3 if the group’s membership is not managed manually.

Request: CreateGroupMembershipRequest

group_membership GroupMembership required

​

Fields of GroupMembership
key GroupMembershipKey required

Identity is a nested key so delete can address a membership without the full resource, which may gain fields later.

Fields of GroupMembershipKey
group_rid string required

At most 256 characters.

member_rid string required

The member of the group. Only user RIDs are accepted today. At most 256 characters.

Response: CreateGroupMembershipResponse

group_membership GroupMembership

​

Fields of GroupMembership
key GroupMembershipKey

Identity is a nested key so delete can address a membership without the full resource, which may gain fields later.

Fields of GroupMembershipKey
group_rid string

At most 256 characters.

member_rid string

The member of the group. Only user RIDs are accepted today. At most 256 characters.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.CreateGroupMembershipRequest(
    group_membership={"key": {"group_rid": "<group rid>", "member_rid": "<member rid>"}},
)
response = group_service.CreateGroupMembership(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.CreateGroupMembershipRequest{
		GroupMembership: &groupsv1.GroupMembership{
			Key: &groupsv1.GroupMembershipKey{
				GroupRid:  "<group rid>",
				MemberRid: "<member rid>",
			},
		},
	}
	response, err := groupService.CreateGroupMembership(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "group_membership": {
    "key": {
      "group_rid": "<group rid>",
      "member_rid": "<member rid>"
    }
  }
}

Create or update group#

gRPC /nominal.authentication.groups.v1.GroupService/CreateOrUpdateGroup

Org-scoped upsert.

Creates a new group if Group.rid is empty in the request (server assigns the rid). Both Group.org_rid and Group.group_id are required on create, and the new group_id must be unique within the organization.

Updates an existing group if Group.rid is present in the request. Group.org_rid and Group.group_id are immutable: when set on the update request they must match the existing values, but they may be omitted to leave them unchanged. Fields in the group message marked as OUTPUT_ONLY are ignored when present in the input request. All other mutable fields are fully overwritten, and will be cleared if not set in the request.

Throws HTTP 400 / gRPC 3 if a supplied immutable field does not match the existing group. Throws HTTP 404 / gRPC 5 if the group identified by Group.rid for an update does not exist. Throws HTTP 409 / gRPC 6 if a create would result in duplicate group_ids within the organization. Throws HTTP 403 / gRPC 7 if the caller is not authorized.

Request: CreateOrUpdateGroupRequest

group Group required

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string output only

The list of users in this group.

created_at string (date-time) output only

​

updated_at string (date-time) output only

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Response: CreateOrUpdateGroupResponse

group Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.CreateOrUpdateGroupRequest(
    group={
        "rid": "<rid>",
        "org_rid": "<org rid>",
        "group_id": "<group id>",
        "display_name": "<display name>",
        "description": "<description>",
        "symbol": {"icon": "<icon>"},
        "membership_managed_manually": True,
    },
)
response = group_service.CreateOrUpdateGroup(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/v1"
	elementsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/scout/elements/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.CreateOrUpdateGroupRequest{
		Group: &groupsv1.Group{
			Rid:         "<rid>",
			OrgRid:      "<org rid>",
			GroupId:     "<group id>",
			DisplayName: "<display name>",
			Description: "<description>",
			Symbol: &elementsv1.Symbol{
				Symbol: &elementsv1.Symbol_Icon{Icon: "<icon>"},
			},
			MembershipManagedManually: true,
		},
	}
	response, err := groupService.CreateOrUpdateGroup(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "group": {
    "rid": "<rid>",
    "org_rid": "<org rid>",
    "group_id": "<group id>",
    "display_name": "<display name>",
    "description": "<description>",
    "user_rids": [
      "<user rids>"
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "symbol": {
      "icon": "<icon>"
    },
    "membership_managed_manually": true
  }
}

Delete group membership#

gRPC /nominal.authentication.groups.v1.GroupService/DeleteGroupMembership

Removes a member from a manually managed group. Removing a non-member is a no-op. Throws HTTP 400 / gRPC 3 if group_rid or member_rid is missing, or member_rid is not a supported RID type. Throws HTTP 403 / gRPC 7 if the caller is not authorized to update the group, including when the group does not exist. The permission check runs before the group lookup so unknown groups are not disclosed. Throws HTTP 400 / gRPC 3 if the group’s membership is not managed manually.

Request: DeleteGroupMembershipRequest

key GroupMembershipKey required

​

Fields of GroupMembershipKey
group_rid string required

At most 256 characters.

member_rid string required

The member of the group. Only user RIDs are accepted today. At most 256 characters.

Response: DeleteGroupMembershipResponse

A message with no fields.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.DeleteGroupMembershipRequest(
    key={"group_rid": "<group rid>", "member_rid": "<member rid>"},
)
response = group_service.DeleteGroupMembership(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.DeleteGroupMembershipRequest{
		Key: &groupsv1.GroupMembershipKey{
			GroupRid:  "<group rid>",
			MemberRid: "<member rid>",
		},
	}
	response, err := groupService.DeleteGroupMembership(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{}

Get group#

gRPC /nominal.authentication.groups.v1.GroupService/GetGroup

Get group within the user’s organization

Request: GetGroupRequest

group_rid string required

​

Response: GetGroupResponse

group Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.GetGroupRequest(group_rid="<group rid>")
response = group_service.GetGroup(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.GetGroupRequest{
		GroupRid: "<group rid>",
	}
	response, err := groupService.GetGroup(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "group": {
    "rid": "<rid>",
    "org_rid": "<org rid>",
    "group_id": "<group id>",
    "display_name": "<display name>",
    "description": "<description>",
    "user_rids": [
      "<user rids>"
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "symbol": {
      "icon": "<icon>"
    },
    "membership_managed_manually": true
  }
}

Get group by ID#

gRPC /nominal.authentication.groups.v1.GroupService/GetGroupById

Gets a group by its ID within the user’s organization

Request: GetGroupByIdRequest

group_id string required

​

Response: GetGroupByIdResponse

group Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.GetGroupByIdRequest(group_id="<group id>")
response = group_service.GetGroupById(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.GetGroupByIdRequest{
		GroupId: "<group id>",
	}
	response, err := groupService.GetGroupById(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "group": {
    "rid": "<rid>",
    "org_rid": "<org rid>",
    "group_id": "<group id>",
    "display_name": "<display name>",
    "description": "<description>",
    "user_rids": [
      "<user rids>"
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "symbol": {
      "icon": "<icon>"
    },
    "membership_managed_manually": true
  }
}

Get groups#

gRPC /nominal.authentication.groups.v1.GroupService/GetGroups

Get batch of groups within the user’s organization

Request: GetGroupsRequest

group_rids array of string

​

Response: GetGroupsResponse

groups map of string to Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.GetGroupsRequest(group_rids=["<group rids>"])
response = group_service.GetGroups(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.GetGroupsRequest{
		GroupRids: []string{
			"<group rids>",
		},
	}
	response, err := groupService.GetGroups(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "groups": {
    "<key>": {
      "rid": "<rid>",
      "org_rid": "<org rid>",
      "group_id": "<group id>",
      "display_name": "<display name>",
      "description": "<description>",
      "user_rids": [
        "<user rids>"
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "symbol": {
        "icon": "<icon>"
      },
      "membership_managed_manually": true
    }
  }
}

Search groups#

gRPC /nominal.authentication.groups.v1.GroupService/SearchGroups

Searches all groups in the user’s organization using given query

Request: SearchGroupsRequest

page_size integer

Page sizes greater than 1_000 will be rejected. Default pageSize is 100.

next_page_token string

​

query SearchGroupsQuery required

​

Fields of SearchGroupsQuery
one of exact_substring_text, and, or, member_users

​

exact_substring_text string

​

and SearchQueryAnd

and is implemented to allow for list (use SearchQueryAnd([]))

Fields of SearchQueryAnd
queries array of SearchGroupsQuery

​

or SearchQueryOr

​

Fields of SearchQueryOr
queries array of SearchGroupsQuery

​

member_users SearchQueryMemberUsers

​

Fields of SearchQueryMemberUsers
user_rids array of string

1 to 1,000 items. Each item: at most 256 characters.

Response: SearchGroupsResponse

results array of Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

next_page_token string

​

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.SearchGroupsRequest(
    query={"exact_substring_text": "<exact substring text>"},
)
response = group_service.SearchGroups(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.SearchGroupsRequest{
		Query: &groupsv1.SearchGroupsQuery{
			Query: &groupsv1.SearchGroupsQuery_ExactSubstringText{ExactSubstringText: "<exact substring text>"},
		},
	}
	response, err := groupService.SearchGroups(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "results": [
    {
      "rid": "<rid>",
      "org_rid": "<org rid>",
      "group_id": "<group id>",
      "display_name": "<display name>",
      "description": "<description>",
      "user_rids": [
        "<user rids>"
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "symbol": {
        "icon": "<icon>"
      },
      "membership_managed_manually": true
    }
  ],
  "next_page_token": "<next page token>"
}

Update group metadata#

gRPC /nominal.authentication.groups.v1.GroupService/UpdateGroupMetadata

Updates the metadata of a group

Request: UpdateGroupMetadataRequestWrapper

group_rid string required

​

request UpdateGroupMetadataRequest required

​

Fields of UpdateGroupMetadataRequest
display_name string

​

description string

​

symbol UpdateGroupSymbolWrapper

​

Fields of UpdateGroupSymbolWrapper
value Symbol

​

Fields of Symbol
one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

Response: UpdateGroupMetadataResponse

group Group

​

Fields of Group
rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string

The list of users in this group.

created_at string (date-time)

​

updated_at string (date-time)

​

symbol Symbol

Symbol to identify groups

Fields of Symbol
one of icon, emoji, image

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

Request

import grpc
from nominal.protos.authentication.groups.v1 import groups_pb2, groups_pb2_grpc

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

request = groups_pb2.UpdateGroupMetadataRequestWrapper(
    group_rid="<group rid>",
    request={
        "display_name": "<display name>",
        "description": "<description>",
        "symbol": {"value": {"icon": "<icon>"}},
    },
)
response = group_service.UpdateGroupMetadata(request, metadata=auth)
print(response)

package main

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

	groupsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/authentication/groups/v1"
	elementsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/scout/elements/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

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()
	groupService := groupsv1.NewGroupServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &groupsv1.UpdateGroupMetadataRequestWrapper{
		GroupRid: "<group rid>",
		Request: &groupsv1.UpdateGroupMetadataRequest{
			DisplayName: proto.String("<display name>"),
			Description: proto.String("<description>"),
			Symbol: &groupsv1.UpdateGroupMetadataRequest_UpdateGroupSymbolWrapper{
				Value: &elementsv1.Symbol{
					Symbol: &elementsv1.Symbol_Icon{Icon: "<icon>"},
				},
			},
		},
	}
	response, err := groupService.UpdateGroupMetadata(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "group": {
    "rid": "<rid>",
    "org_rid": "<org rid>",
    "group_id": "<group id>",
    "display_name": "<display name>",
    "description": "<description>",
    "user_rids": [
      "<user rids>"
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "symbol": {
      "icon": "<icon>"
    },
    "membership_managed_manually": true
  }
}

Errors#

Errors shows how these errors are sent.

Code

Reason

Message

INVALID_ARGUMENT

GROUP_ERRORS_IDENTITY_MISMATCH

Request identity field does not match the existing group

INVALID_ARGUMENT

GROUP_ERRORS_INVALID_RID

RID field is invalid

INVALID_ARGUMENT

GROUP_ERRORS_MEMBERSHIP_NOT_MANAGED_MANUALLY

Group membership is not managed manually

INVALID_ARGUMENT

GROUP_ERRORS_MISSING_REQUIRED_FIELD

Required field missing on request

INVALID_ARGUMENT

GROUP_ERRORS_REQUESTED_PAGE_SIZE_TOO_LARGE

Requested page size is too large

INVALID_ARGUMENT

GROUP_ERRORS_USER_NOT_IN_ORG

User is not a member of the group organization

NOT_FOUND

GROUP_ERRORS_NOT_FOUND

Group not found

ALREADY_EXISTS

GROUP_ERRORS_ID_CONFLICT

Group with given group_id already exists in organization

PERMISSION_DENIED

GROUP_ERRORS_UNAUTHORIZED

Not authorized for group

Types#

Group#

A group represents a collection of users within an organization

rid string

​

org_rid string

Required on create requests; immutable on updates.

group_id string

Group ID, unique per org. If sourced from the customer’s IdP, will match IdP group name. Required on create requests; immutable on updates.

display_name string

​

description string

​

user_rids array of string output only

The list of users in this group.

created_at string (date-time) output only

​

updated_at string (date-time) output only

​

symbol Symbol

Symbol to identify groups

membership_managed_manually boolean

Whether group membership is managed manually in Nominal. Defaults to false.

GroupMembership#

A membership in a group.

key GroupMembershipKey required

Identity is a nested key so delete can address a membership without the full resource, which may gain fields later.

GroupMembershipKey#

Client-known identity of a group membership.

group_rid string required

At most 256 characters.

member_rid string required

The member of the group. Only user RIDs are accepted today. At most 256 characters.

SearchGroupsQuery#

Set at most one of the fields below.

one of exact_substring_text, and, or, member_users

​

exact_substring_text string

​

and SearchQueryAnd

and is implemented to allow for list (use SearchQueryAnd([]))

or SearchQueryOr

​

member_users SearchQueryMemberUsers

​

SearchQueryAnd#

queries array of SearchGroupsQuery

​

SearchQueryMemberUsers#

Matches the groups that any of the users is a direct member of, whether that membership is synced from the identity provider or managed manually.

user_rids array of string

1 to 1,000 items. Each item: at most 256 characters.

SearchQueryOr#

queries array of SearchGroupsQuery

​

Symbol#

Set exactly one of the fields below.

one of icon, emoji, image required

​

icon string

Icon name (e.g. castle)

emoji string

Emoji name (e.g. :castle:)

image string

Image url (e.g. https://example.com/image.png)

UpdateGroupMetadataRequest#

display_name string

​

description string

​

symbol UpdateGroupSymbolWrapper

​

UpdateGroupSymbolWrapper#

value Symbol

​

Page design based on Scalar, MIT License.