GetAPIUserByKeyHash

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.

Overview

Method Options

Authorisation specification of the GetAPIUserByKeyHash method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_IAM_ADMIN ROLE_IAM_VIEWER ROLE_IAM_API_USER_ADMIN ROLE_IAM_API_USER_VIEWER

Parameters

Request and response parameter message overview:

Input: GetAPIUserByKeyHashRequest Message

Field	Type	Required	Description
KeyHash	string	True	Key hash of the API user to get.

Returns: APIUser Message

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/option/method_options/v1/method_options.proto";

option go_package = "github.com/meshtrade/api/go/iam/api_user/v1;api_user_v1";
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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_API_USER_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_API_USER_ADMIN
      ]
    };
  }

  /*
     Assign roles to an existing api user within the authenticated group context.

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

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

     The role revocation removes the permissions associated with that role from
     the API user within the group hierarchy. The API user will no longer be able
     to perform operations that require the revoked role.
  */
  rpc RevokeRolesFromAPIUser(RevokeRolesFromAPIUserRequest) returns (meshtrade.iam.api_user.v1.APIUser) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_API_USER_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_API_USER_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_API_USER_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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_API_USER_ADMIN,
        ROLE_IAM_API_USER_VIEWER
      ]
    };
  }
}

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

message GetAPIUserByKeyHashRequest {
  /*
     Key hash of the API user to get.
  */
  string key_hash = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 44
      pattern: "^[A-Za-z0-9+/]{43}=$"
    }
  }];
}

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 [(buf.validate.field) = {required: true}];
}

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

  /*
     Roles to assign to the API 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 RevokeRolesFromAPIUserRequest {
  /*
     Name of the API user to revoke roles from in the format iam/api_users/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {pattern: "^iam/api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];

  /*
     Roles to revoke from the API 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 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.
     Format: iam/api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {pattern: "^iam/api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];
}

message DeactivateAPIUserRequest {
  /*
     Name of the API user to deactivate.
     Format: iam/api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {pattern: "^iam/api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];
}

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"

	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.GetAPIUserByKeyHashRequest{
		// FIXME: Populate service-specific request fields
	}

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

	// FIXME: Add relevant response object usage
	log.Printf("GetAPIUserByKeyHash successful: %+v", apiUser)
}

Python

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


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 = GetAPIUserByKeyHashRequest(
            # FIXME: Populate service-specific request fields
        )

        # Call the GetAPIUserByKeyHash method
        api_user = service.get_api_user_by_key_hash(request)

        # FIXME: Add relevant response object usage
        print("GetAPIUserByKeyHash successful:", api_user)


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.api_user.v1.ApiUserService;
import co.meshtrade.api.iam.api_user.v1.Service.GetAPIUserByKeyHashRequest;
import co.meshtrade.api.iam.api_user.v1.ApiUser.APIUser;

import java.util.Optional;

public class GetAPIUserByKeyHashExample {
    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
            GetAPIUserByKeyHashRequest request = GetAPIUserByKeyHashRequest.newBuilder()
                // FIXME: Populate service-specific request fields
                .build();

            // Call the GetAPIUserByKeyHash method
            APIUser apiUser = service.getAPIUserByKeyHash(request, Optional.empty());

            // FIXME: Add relevant response object usage
            System.out.println("GetAPIUserByKeyHash successful: " + apiUser);
        } catch (Exception e) {
            System.err.println("GetAPIUserByKeyHash 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 Api User v1 Method List - For Other methods