RevokeRoleFromAPIUser

Method Details

Description: Revokes a role 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.

Required Roles: Check proto file for roles

Parameters:

• Name (string) (required): Name of the API user to revoke a role from. Format: api_users/{ULIDv2}
• Role (string) (required): Role to revoke from the API user in the format groups/{ULIDv2}/{role_id}. The role_id corresponds to a value from the meshtrade.iam.role.v1.Role enum.

Returns: APIUser

Method Type: Unknown

Code Examples

Go

package main

import (
	"context"
	"log"

	api_userv1 "github.com/meshtrade/api/go/iam/api_user/v1"
	rolev1 "github.com/meshtrade/api/go/iam/role/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()

	// Revoke role from existing API user
	request := &api_userv1.RevokeRoleFromAPIUserRequest{
		Name: "api_users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6", // API user to revoke role from
		Role: rolev1.Role_ROLE_IAM_VIEWER.FullResourceNameFromGroupName(service.Group()),
	}

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

	// Role has been successfully revoked
	log.Printf("Role revoked successfully:")
	log.Printf("  API User: %s", apiUser.Name)
	log.Printf("  Display Name: %s", apiUser.DisplayName)
	log.Printf("  Remaining Roles: %d", len(apiUser.Roles))
}

Python

"""Example: Revoke a role from an API user."""

from meshtrade.api.iam.api_user.v1 import (
    ApiUserService,
    RevokeRoleFromAPIUserRequest,
)
from meshtrade.api.iam.role.v1.role import full_resource_name_from_group_name
from meshtrade.api.iam.role.v1.role_pb2 import Role


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:
        # Revoke role from existing API user
        request = RevokeRoleFromAPIUserRequest(
            name="api_users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6",  # API user to revoke role from
            role=full_resource_name_from_group_name(Role.ROLE_IAM_VIEWER, service.group()),
        )

        # Call the RevokeRoleFromAPIUser method
        api_user = service.revoke_role_from_api_user(request)

        # Role has been successfully revoked
        print("Role revoked successfully:")
        print(f"  API User: {api_user.name}")
        print(f"  Display Name: {api_user.display_name}")
        print(f"  Remaining Roles: {len(api_user.roles)}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.api_user.v1.ApiUserService;
import co.meshtrade.api.iam.api_user.v1.Service.RevokeRoleFromAPIUserRequest;
import co.meshtrade.api.iam.api_user.v1.ApiUser.APIUser;
import co.meshtrade.api.iam.role.v1.RoleUtils;
import co.meshtrade.api.iam.role.v1.RoleOuterClass.Role;

import java.util.Optional;

public class RevokeRoleFromAPIUserExample {
    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()) {
            // Revoke role from existing API user
            RevokeRoleFromAPIUserRequest request = RevokeRoleFromAPIUserRequest.newBuilder()
                .setName("api_users/01HN2ZXQJ8K9M0L1N3P2Q4R5T6")  // API user to revoke role from
                .setRole(RoleUtils.fullResourceNameFromGroupName(Role.ROLE_IAM_VIEWER, service.getGroup()))
                .build();

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

            // Role has been successfully revoked
            System.out.println("Role revoked successfully:");
            System.out.println("  API User: " + apiUser.getName());
            System.out.println("  Display Name: " + apiUser.getDisplayName());
            System.out.println("  Remaining Roles: " + apiUser.getRolesCount());
        } catch (Exception e) {
            System.err.println("RevokeRoleFromAPIUser 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_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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_API_USER_ADMIN        
      ]
    };
  }

  /*
     Assigns a role 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 AssignRoleToAPIUser(AssignRoleToAPIUserRequest) 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,
        ROLE_IAM_API_USER_ADMIN
      ]
    };
  }

  /*
     Revokes a role 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 RevokeRoleFromAPIUser(RevokeRoleFromAPIUserRequest) 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,
        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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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: api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true,
    string: {
      len: 36,
      pattern: "^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 AssignRoleToAPIUserRequest {
  /*
     Name of the api user to assign a role to.
  */
  string name = 1 [(buf.validate.field) = {
    required: true,
    string: {
      len: 36,
      pattern: "^api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     Role to assign to the api user in the format groups/{ULIDv2}/{role_id}.
     The role_id corresponds to a value from the meshtrade.iam.role.v1.Role enum.
  */
  string role = 4 [(buf.validate.field) = {
    required: true,
    string: {
      len: 41,
      pattern: "^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}/[1-9][0-9]{6}$"
    }
  }];
}

message RevokeRoleFromAPIUserRequest {
  /*
     Name of the API user to revoke a role from.
     Format: api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true,
    string: {
      len: 36,
      pattern: "^api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

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

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: api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true,
    string: {
      len: 36,
      pattern: "^api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

message DeactivateApiUserRequest {
  /*
     Name of the API user to deactivate.
     Format: api_users/{ULIDv2}
  */
  string name = 1 [(buf.validate.field) = {
    required: true,
    string: {
      len: 36,
      pattern: "^api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{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