GetUser

Retrieves a single user by their unique identifier.

Returns user details including name, email, ownership information, and assigned roles within the authenticated group's access scope.

Overview

Method Options

Authorisation specification of the GetUser method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_IAM_ADMIN ROLE_IAM_VIEWER ROLE_IAM_USER_ADMIN ROLE_IAM_USER_VIEWER

Parameters

Request and response parameter message overview:

Input: GetUserRequest Message

Field	Type	Required	Description
Name	string	True	Name of the user to retrieve. Format: users/{ULIDv2}

Returns: User Message

Protobuf

syntax = "proto3";

package meshtrade.iam.user.v1;

import "buf/validate/validate.proto";
import "meshtrade/iam/user/v1/user.proto";
import "meshtrade/option/method_options/v1/method_options.proto";
import "meshtrade/type/v1/sorting.proto";

option go_package = "github.com/meshtrade/api/go/iam/user/v1;user_v1";
option java_package = "co.meshtrade.api.iam.user.v1";

/*
   UserService manages user lifecycle and identity operations within groups.

   Users are individual identity entities that belong to specific groups and have
   assigned roles that determine their permissions within that group context.
   Each user has a unique email address and can be assigned multiple roles
   across the group hierarchy for fine-grained access control.

   All operations require appropriate IAM domain permissions and operate within
   the authenticated group context.
*/
service UserService {
  /*
     Assign roles to an existing user within the authenticated group context.

     The role assignment enables the user to perform operations according
     to the permissions associated with that role within the group hierarchy.
  */
  rpc AssignRolesToUser(AssignRolesToUserRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_ADMIN
      ]
    };
  }

  /*
     Revoke roles from an existing user within the authenticated group context.

     The role revocation removes the permissions associated with that role from
     the user within the group hierarchy. The user will no longer be able
     to perform operations that require the revoked role.
  */
  rpc RevokeRolesFromUser(RevokeRolesFromUserRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_ADMIN
      ]
    };
  }

  /*
     Retrieves a single user by their unique identifier.

     Returns user details including name, email, ownership information,
     and assigned roles within the authenticated group's access scope.
  */
  rpc GetUser(GetUserRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_ADMIN,
        ROLE_IAM_USER_VIEWER
      ]
    };
  }

  /*
     Retrieves a single user by their email address.

     Returns user details including name, email, ownership information,
     and assigned roles within the authenticated group's access scope.
  */
  rpc GetUserByEmail(GetUserByEmailRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_ADMIN,
        ROLE_IAM_USER_VIEWER
      ]
    };
  }

  /*
     Returns all users accessible within the authenticated group's hierarchy.

     Results include users directly owned and those accessible through the
     group's hierarchical permissions, optionally sorted by email address.
  */
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_ADMIN,
        ROLE_IAM_USER_VIEWER
      ]
    };
  }

  /*
     Searches for users by email substring within the authenticated group's hierarchy.

     Returns users whose email addresses contain the provided search string,
     useful for type-ahead and fuzzy-matching use cases.
  */
  rpc SearchUsers(SearchUsersRequest) returns (SearchUsersResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_ADMIN,
        ROLE_IAM_USER_VIEWER
      ]
    };
  }

  /*
     Creates a new user within the authenticated group context.

     The user will be created with the provided email and group ownership,
     with system-generated unique identifier and ownership hierarchy.
     Additional roles can be assigned after creation.
  */
  rpc CreateUser(CreateUserRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_ADMIN
      ]
    };
  }

  /*
     Updates an existing user with modified field values.

     Only mutable fields can be updated while preserving system-generated
     identifiers and ownership relationships. Role modifications should
     use dedicated role management operations.
  */
  rpc UpdateUser(UpdateUserRequest) returns (meshtrade.iam.user.v1.User) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_ADMIN
      ]
    };
  }
}

message AssignRolesToUserRequest {
  /*
     Name of the user to assign roles to in the format users/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 32
      pattern: "^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     Roles to assign to the user in the format groups/{ULIDv2}/roles/{role_id}.
     The role_id corresponds to a value from the meshtrade.iam.role.v1.Role enum.
  */
  repeated string roles = 2 [(buf.validate.field) = {
    required: true
    repeated: {
      items: {
        string: {
          min_len: 47
          max_len: 48
          pattern: "^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}/roles/[1-9][0-9]{6,7}$"
        }
      }
    }
  }];
}

message RevokeRolesFromUserRequest {
  /*
     Name of the user to revoke roles from in the format users/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 32
      pattern: "^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     Roles to revoke from the user in the format groups/{ULIDv2}/roles/{role_id}.
     The role_id corresponds to a value from the meshtrade.iam.role.v1.Role enum.
  */
  repeated string roles = 2 [(buf.validate.field) = {
    required: true
    repeated: {
      items: {
        string: {
          min_len: 47
          max_len: 48
          pattern: "^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}/roles/[1-9][0-9]{6,7}$"
        }
      }
    }
  }];
}

message GetUserRequest {
  /*
     Name of the user to retrieve.
     Format: users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 32
      pattern: "^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

message GetUserByEmailRequest {
  /*
     Email address of the user to retrieve.
     Must be a valid email address format.
  */
  string email = 1 [(buf.validate.field) = {
    required: true
    string: {email: true}
  }];
}

message ListUsersRequest {
  message Sorting {
    /*
       Field to sort by (e.g., "email").
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "email"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: email, or empty"
        expression: "this in ['', 'email']"
      }
    }];
    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }
  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;
}

message ListUsersResponse {
  repeated meshtrade.iam.user.v1.User users = 1;
}

message SearchUsersRequest {
  /*
     Optional Substring to match against user email addresses.
     The search is case-insensitive.
  */
  string email = 1 [(buf.validate.field) = {
    string: {max_len: 100}
  }];
}

message SearchUsersResponse {
  repeated meshtrade.iam.user.v1.User users = 1;
}

message CreateUserRequest {
  /*
     The user resource to create.
     The name field will be ignored and assigned by the server.
  */
  meshtrade.iam.user.v1.User user = 1 [(buf.validate.field) = {required: true}];
}

message UpdateUserRequest {
  /*
     Complete user resource with updated fields.
     Only mutable fields can be modified.
  */
  meshtrade.iam.user.v1.User user = 1 [(buf.validate.field) = {required: true}];
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"log"

	userv1 "github.com/meshtrade/api/go/iam/user/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := userv1.NewUserService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with user resource name
	request := &userv1.GetUserRequest{
		Name: "users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6", // User ULIDv2 identifier
	}

	// Call the GetUser method
	user, err := service.GetUser(ctx, request)
	if err != nil {
		log.Fatalf("GetUser failed: %v", err)
	}

	// Access user details and hierarchy information
	log.Printf("User retrieved successfully:")
	log.Printf("  Name: %s", user.Name)
	log.Printf("  Email: %s", user.Email)
	log.Printf("  Owner: %s", user.Owner)
	// System maintains hierarchical ownership relationships internally
	log.Printf("  Assigned Roles: %v", user.Roles)
	
	// Use user information for access validation
	if len(user.Roles) > 0 {
		log.Printf("User has %d active role assignments", len(user.Roles))
	}
}

Python

from meshtrade.iam.user.v1 import (
    GetUserRequest,
    UserService,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = UserService()

    with service:
        # Create request to get a specific user by name (resource identifier)
        request = GetUserRequest(
            name="users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6"  # User resource name
        )

        # Call the GetUser method
        user = service.get_user(request)

        # Use the retrieved user information
        print("Retrieved user successfully:")
        print(f"  Name: {user.name}")  # System-generated identifier
        print(f"  Email: {user.email}")  # Email address for identification
        print(f"  Owner: {user.owner}")  # Direct group owner
        print(f"  Owners: {user.owners}")  # Full ownership hierarchy
        print(f"  Roles: {user.roles}")  # Assigned roles across groups

        # User information can be used for profile display or access validation
        print(f"User {user.email} profile loaded for management interface")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.user.v1.UserService;
import co.meshtrade.api.iam.user.v1.Service.GetUserRequest;
import co.meshtrade.api.iam.user.v1.User.User;

import java.util.Optional;

public class GetUserExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (UserService service = new UserService()) {
            // Create request to get a specific user by name (resource identifier)
            GetUserRequest request = GetUserRequest.newBuilder()
                .setName("users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6")  // User resource name
                .build();

            // Call the GetUser method
            User user = service.getUser(request, Optional.empty());

            // Use the retrieved user information
            System.out.println("Retrieved user successfully:");
            System.out.println("  Name: " + user.getName());           // System-generated identifier
            System.out.println("  Email: " + user.getEmail());         // Email address for identification
            System.out.println("  Owner: " + user.getOwner());         // Direct group owner
            System.out.println("  Owners: " + user.getOwnersList());   // Full ownership hierarchy
            System.out.println("  Roles: " + user.getRolesList());     // Assigned roles across groups
            
            // User information can be used for profile display or access validation
            System.out.println("User " + user.getEmail() + " profile loaded for management interface");
        } catch (Exception e) {
            System.err.println("GetUser failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Iam User v1 Method List - For Other methods