SearchApiUsers

Method Details

Description: Searches API users using display name filtering.

Performs substring matching on API user display names within the authenticated group context.

Required Roles: Check proto file for roles

Parameters:

• DisplayName (string): Display name is a substring search for API users.

Returns: SearchApiUsersResponse

Method Type: METHOD_TYPE_READ

Code Examples

Go

package main

import (
	"context"
	"log"

	api_userv1 "github.com/meshtrade/api/go/iam/api_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 := api_userv1.NewApiUserService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with service-specific parameters
	request := &api_userv1.SearchApiUsersRequest{
		DisplayName: "Integration", // Search for API users with "Integration" in display name
	}

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

	// Process search results
	log.Printf("Found %d API users matching search criteria", len(response.GetApiUsers()))
	
	for i, apiUser := range response.GetApiUsers() {
		log.Printf("Match %d:", i+1)
		log.Printf("  Name: %s", apiUser.GetName())
		log.Printf("  Display Name: %s", apiUser.GetDisplayName())
		log.Printf("  State: %s", apiUser.GetState().String())
		log.Printf("  Owner: %s", apiUser.GetOwner())
	}
	
	if len(response.GetApiUsers()) == 0 {
		log.Printf("No API users found matching the search criteria")
	}
}

Python

from meshtrade.iam.api_user.v1 import (
    ApiUserService,
    SearchApiUsersRequest,
)


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 = ApiUserService()

    with service:
        # Create request with service-specific parameters
        request = SearchApiUsersRequest(
            display_name="Integration"  # Search for API users with "Integration" in display name
        )

        # Call the SearchApiUsers method
        response = service.search_api_users(request)

        # Process search results
        print(f"Found {len(response.api_users)} API users matching search criteria")

        for i, api_user in enumerate(response.api_users, 1):
            print(f"Match {i}:")
            print(f"  Name: {api_user.name}")
            print(f"  Display Name: {api_user.display_name}")
            print(f"  State: {api_user.state}")
            print(f"  Owner: {api_user.owner}")

        if not response.api_users:
            print("No API users found matching the search criteria")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.api_user.v1.ApiUserService;
import co.meshtrade.api.iam.api_user.v1.Service.SearchApiUsersRequest;
import co.meshtrade.api.iam.api_user.v1.Service.SearchApiUsersResponse;

import java.util.Optional;

public class SearchApiUsersExample {
    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 (ApiUserService service = new ApiUserService()) {
            // Create request with service-specific parameters
            SearchApiUsersRequest request = SearchApiUsersRequest.newBuilder()
                .setDisplayName("Integration") // Search for API users with "Integration" in display name
                .build();

            // Call the SearchApiUsers method
            SearchApiUsersResponse response = service.searchApiUsers(request, Optional.empty());

            // Process search results
            System.out.println("Found " + response.getApiUsersCount() + " API users matching search criteria");
            
            for (int i = 0; i < response.getApiUsersCount(); i++) {
                var apiUser = response.getApiUsers(i);
                System.out.println("Match " + (i + 1) + ":");
                System.out.println("  Name: " + apiUser.getName());
                System.out.println("  Display Name: " + apiUser.getDisplayName());
                System.out.println("  State: " + apiUser.getState());
                System.out.println("  Owner: " + apiUser.getOwner());
            }
            
            if (response.getApiUsersCount() == 0) {
                System.out.println("No API users found matching the search criteria");
            }
        } catch (Exception e) {
            System.err.println("SearchApiUsers failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Protobuf

syntax = "proto3";

package meshtrade.iam.api_user.v1;

import "buf/validate/validate.proto";
import "meshtrade/iam/api_user/v1/api_user.proto";
import "meshtrade/iam/role/v1/role.proto";
import "meshtrade/option/v1/method_type.proto";

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

/*
   ApiUserService manages API user lifecycle and authentication credentials.

   API users represent automated clients that can authenticate with API keys
   and perform operations within a specific group context. Each API user has:
   - A unique identifier and display name
   - Group ownership for resource isolation
   - Role-based permissions for authorization
   - Active/inactive state for access control

   All operations require IAM domain permissions and operate within
   the authenticated group context.
*/
service ApiUserService {
  /*
     Retrieves a single API user by its unique identifier.
  */
  rpc GetApiUser(GetApiUserRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER
      ]
    };
  }

  /*
     Creates a new API user with the specified configuration.

     The API user will be created in the authenticated group context
     and assigned the provided roles. The system generates a unique
     identifier and API key for authentication.
  */
  rpc CreateApiUser(CreateApiUserRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [ROLE_IAM_ADMIN]
    };
  }

  /*
     Lists all API users in the authenticated group context.

     Returns all API users that belong to the current group,
     regardless of their active/inactive state.
  */
  rpc ListApiUsers(ListApiUsersRequest) returns (ListApiUsersResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER
      ]
    };
  }

  /*
     Searches API users using display name filtering.

     Performs substring matching on API user display names
     within the authenticated group context.
  */
  rpc SearchApiUsers(SearchApiUsersRequest) returns (SearchApiUsersResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER
      ]
    };
  }

  /*
     Activates an API user, enabling API key authentication.

     Changes the API user state to active, allowing the associated
     API key to be used for authentication and authorization.
  */
  rpc ActivateApiUser(ActivateApiUserRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [ROLE_IAM_ADMIN]
    };
  }

  /*
     Deactivates an API user, disabling API key authentication.

     Changes the API user state to inactive, preventing the associated
     API key from being used for authentication.
  */
  rpc DeactivateApiUser(DeactivateApiUserRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [ROLE_IAM_ADMIN]
    };
  }

  /*
     Retrieves an API user using its API key hash.

     This method is used for authentication flows to lookup
     an API user based on the hash of their API key.
  */
  rpc GetApiUserByKeyHash(GetApiUserByKeyHashRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER
      ]
    };
  }
}

message GetApiUserRequest {
  /*
     Name of the API user to get.
  */
  string name = 1;
}

message GetApiUserByKeyHashRequest {
  /*
     Key hash of the API user to get.
  */
  string key_hash = 1;
}

message CreateApiUserRequest {
  /*
     The API user resource to create.
     The name field will be ignored and assigned by the server.
  */
  meshtrade.iam.api_user.v1.APIUser api_user = 1;
}

message ListApiUsersRequest {}

message ListApiUsersResponse {
  repeated meshtrade.iam.api_user.v1.APIUser api_users = 1;
}

message SearchApiUsersRequest {
  /*
     Display name is a substring search for API users.
  */
  string display_name = 1;
}

message SearchApiUsersResponse {
  repeated meshtrade.iam.api_user.v1.APIUser api_users = 1;
}

message ActivateApiUserRequest {
  /*
     Name of the API user to activate.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      min_len: 1
      pattern: "^api_users/[0-9A-HJKMNP-TV-Z]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format api_users/{id}"
      expression: "this.matches('^api_users/[0-9A-HJKMNP-TV-Z]{26}$')"
    }
  }];
}

message DeactivateApiUserRequest {
  /*
     Name of the API user to deactivate.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      min_len: 1
      pattern: "^api_users/[0-9A-HJKMNP-TV-Z]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format api_users/{id}"
      expression: "this.matches('^api_users/[0-9A-HJKMNP-TV-Z]{26}$')"
    }
  }];
}

Advanced Configuration

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

Other Methods

• Iam Api User v1 Method List - For Other methods