gRPC Specification#

The service is defined in the nvidia.omniverse.userinfo.v1alpha package and provides equivalent functionality to the REST API using Protocol Buffers.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this section are to be interpreted as described in RFC 2119.

Service definition — UserInfoService#

RPC	Request	Response	Description
`GetCurrentUser`	`GetCurrentUserRequest`	`User`	Returns the profile of the currently authenticated user. The caller’s identity is determined from the bearer token in the `authorization` gRPC metadata key and resolved against the local directory cache.
`ListUsers`	`ListUsersRequest`	`ListUsersResponse`	Lists users in the directory. Supports optional filtering by `email` (exact match) or `display_name` (prefix with `*` suffix, or substring). Results are paginated using `page_size` and `page_token`.
`GetUser`	`GetUserRequest`	`User`	Returns a single user by their unique identity provider identifier. Returns `NOT_FOUND` if the user does not exist.
`ListGroups`	`ListGroupsRequest`	`ListGroupsResponse`	Lists groups in the directory. Supports optional filtering by `display_name` (prefix or substring). Results are paginated.
`GetGroup`	`GetGroupRequest`	`Group`	Returns a single group by its unique identity provider identifier. Returns `NOT_FOUND` if the group does not exist.
`ListGroupMembers`	`ListGroupMembersRequest`	`ListGroupMembersResponse`	Lists the users that are direct members of a specific group. Supports optional filtering by `email` (exact match) or `display_name` (prefix or substring). Results are paginated.
`ListUserGroups`	`ListUserGroupsRequest`	`ListUserGroupsResponse`	Lists the groups that a specific user is a direct member of. Supports optional display-name filtering and pagination.
`GetUserGroup`	`GetUserGroupRequest`	`Group`	Checks whether a user is a direct member of a group. Returns the group details if the user is a member. Returns `NOT_FOUND` if the user is not a direct member or if either entity does not exist.
`GetGroupMember`	`GetGroupMemberRequest`	`User`	Checks whether a user is a direct member of a group. Returns the user details if the user is a member. Returns `NOT_FOUND` if the user is not a member or if either entity does not exist.

Pagination#

List RPCs accept page_size (maximum results per page, capped at 100 server-side) and page_token (opaque continuation token from a previous response). Responses include next_page_token, which is empty when there are no more results.

Error codes#

gRPC Status	REST Equivalent	Description
`UNAUTHENTICATED`	`401`	Missing or invalid bearer token.
`PERMISSION_DENIED`	`403`	Insufficient permissions.
`NOT_FOUND`	`404`	User or group does not exist, or membership check failed.
`RESOURCE_EXHAUSTED`	`429`	Identity provider rate limit exceeded.
`UNAVAILABLE`	`502`	Identity provider returned an unexpected error.
`INTERNAL`	`500`	Unexpected internal error.

Service discovery — CapabilitiesService#

The service also implements the Omniverse discovery CapabilitiesService (nvidia.omniverse.discovery.capabilities.v2alpha.CapabilitiesService) so discovery clients scanning by the userinfo service type can enumerate the public APIs this server exposes at runtime.

RPC	Request	Response	Description
`ListServices`	`ListServicesRequest`	`ListServicesResponse`	Returns a single `ServiceEntry` for the `userinfo` service type, advertising the gRPC service `nvidia.omniverse.userinfo.v1alpha.UserInfoService` and the REST endpoint `userinfo` (version `v1alpha`, path `/api/v1alpha/`).

The CapabilitiesService is unauthenticated by design, matching discovery-scan expectations, and is registered alongside the health and reflection services. Only ListServices is served; the service definition does not include any other RPC. The advertised gRPC service name is derived from the generated UserInfoService descriptor and the REST version from the REST layer, so the advertisement stays in sync with the actual API surface.

Protocol Buffer definition#

syntax = "proto3";

package nvidia.omniverse.userinfo.v1alpha;

/// A user account in the organization's directory.
message User {
  /// Unique identifier of the user in the directory.
  string id = 1;

  /// Full display name of the user (e.g. "Jane Doe").
  string display_name = 2;

  /// First/given name of the user.
  optional string given_name = 3;

  /// Last/family name of the user.
  optional string family_name = 4;

  /// Primary email address of the user.
  optional string email = 5;

  /// Login username (user principal name).
  string username = 6;

  /// Whether the account is enabled in the directory.
  optional bool active = 7;

  /// Job title as recorded in the directory.
  optional string job_title = 8;
}

/// A security or distribution group in the organization's directory.
message Group {
  /// Unique identifier of the group in the directory.
  string id = 1;

  /// Display name of the group.
  string display_name = 2;

  /// Human-readable description of the group's purpose.
  optional string description = 3;
}

/// Read-only identity service providing user and group information
/// from the organization's directory.
service UserInfoService {
  /// Returns the profile of the currently authenticated user. The caller's
  /// identity is determined from the bearer token in the `authorization` metadata.
  rpc GetCurrentUser(GetCurrentUserRequest) returns (User);

  /// Lists users in the directory with optional filtering by email or display name.
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);

  /// Returns a single user by their unique identifier.
  rpc GetUser(GetUserRequest) returns (User);

  /// Lists groups in the directory with optional display-name filtering.
  rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse);

  /// Returns a single group by its unique identifier.
  rpc GetGroup(GetGroupRequest) returns (Group);

  /// Lists the users that are direct members of a specific group.
  rpc ListGroupMembers(ListGroupMembersRequest) returns (ListGroupMembersResponse);

  /// Lists the groups that a specific user is a direct member of.
  rpc ListUserGroups(ListUserGroupsRequest) returns (ListUserGroupsResponse);

  /// Verifies direct user membership in a group and returns the group details.
  rpc GetUserGroup(GetUserGroupRequest) returns (Group);

  /// Verifies direct user membership in a group and returns the user details.
  rpc GetGroupMember(GetGroupMemberRequest) returns (User);
}

/// Request for GetCurrentUser. The caller's bearer token is passed
/// via the `authorization` gRPC metadata key.
message GetCurrentUserRequest {}

/// Request for ListUsers.
message ListUsersRequest {
  /// Filter by exact email address.
  optional string email = 1;

  /// Filter by display name. Suffix with `*` for prefix matching (e.g. "Jan*"),
  /// or provide a plain string for substring search.
  optional string display_name = 2;

  /// Maximum number of results per page. Capped at 100 server-side.
  int32 page_size = 3;

  /// Opaque pagination token from a previous ListUsersResponse.
  string page_token = 4;
}

/// Response for ListUsers.
message ListUsersResponse {
  /// Users matching the request filters.
  repeated User users = 1;

  /// Token to retrieve the next page. Empty when there are no more results.
  string next_page_token = 2;
}

/// Request for GetUser.
message GetUserRequest {
  /// Unique identifier of the user to retrieve.
  string user_id = 1;
}

/// Request for ListGroups.
message ListGroupsRequest {
  /// Filter by display name. Suffix with `*` for prefix matching,
  /// or provide a plain string for substring search.
  optional string display_name = 1;

  /// Maximum number of results per page. Capped at 100 server-side.
  int32 page_size = 2;

  /// Opaque pagination token from a previous ListGroupsResponse.
  string page_token = 3;
}

/// Response for ListGroups.
message ListGroupsResponse {
  /// Groups matching the request filters.
  repeated Group groups = 1;

  /// Token to retrieve the next page. Empty when there are no more results.
  string next_page_token = 2;
}

/// Request for GetGroup.
message GetGroupRequest {
  /// Unique identifier of the group to retrieve.
  string group_id = 1;
}

/// Request for ListGroupMembers.
message ListGroupMembersRequest {
  /// Unique identifier of the group whose members to list.
  string group_id = 1;

  /// Filter by exact email address.
  optional string email = 2;

  /// Filter by display name. Suffix with `*` for prefix matching (e.g. "Jan*"),
  /// or provide a plain string for substring search.
  optional string display_name = 3;

  /// Maximum number of results per page. Capped at 100 server-side.
  int32 page_size = 4;

  /// Opaque pagination token from a previous ListGroupMembersResponse.
  string page_token = 5;
}

/// Response for ListGroupMembers.
message ListGroupMembersResponse {
  /// Users that are members of the group, matching any filters.
  repeated User users = 1;

  /// Token to retrieve the next page. Empty when there are no more results.
  string next_page_token = 2;
}

/// Request for ListUserGroups.
message ListUserGroupsRequest {
  /// Unique identifier of the user whose groups to list.
  string user_id = 1;

  /// Filter by group display name. Suffix with `*` for prefix matching,
  /// or provide a plain string for substring search.
  optional string display_name = 2;

  /// Maximum number of results per page. Capped at 100 server-side.
  int32 page_size = 3;

  /// Opaque pagination token from a previous ListUserGroupsResponse.
  string page_token = 4;
}

/// Response for ListUserGroups.
message ListUserGroupsResponse {
  /// Groups the user belongs to, matching any filters.
  repeated Group groups = 1;

  /// Token to retrieve the next page. Empty when there are no more results.
  string next_page_token = 2;
}

/// Request for GetUserGroup.
message GetUserGroupRequest {
  /// Unique identifier of the user.
  string user_id = 1;

  /// Unique identifier of the group to check membership for.
  string group_id = 2;
}

/// Request for GetGroupMember.
message GetGroupMemberRequest {
  /// Unique identifier of the group.
  string group_id = 1;

  /// Unique identifier of the user to check membership for.
  string user_id = 2;
}

See next#

Reference documents