CreateApiUser

Method Details

Description: 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.

Required Roles: Check proto file for roles

Parameters:

• ApiUser (message) (required): The API user resource to create. The name field will be ignored and assigned by the server.

Returns: APIUser

Method Type: METHOD_TYPE_WRITE

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

	// Create request with service-specific parameters
	request := &api_userv1.CreateApiUserRequest{
		ApiUser: &api_userv1.APIUser{
			Owner:       service.Group(), // Current group from service context
			DisplayName: "My Integration API Key",
			Roles: []string{
				rolev1.Role_ROLE_IAM_ADMIN.FullResourceNameFromGroupName(service.Group()),
			},
		},
	}

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

	// Access the created API user details
	log.Printf("Successfully created API user: %s", apiUser.GetName())
	log.Printf("API key: %s", apiUser.GetApiKey()) // Only available in creation response
	log.Printf("Display name: %s", apiUser.GetDisplayName())
	log.Printf("State: %s", apiUser.GetState().String()) // Initially INACTIVE
	log.Printf("Owner: %s", apiUser.GetOwner())

	// Note: Store the API key securely - it's only returned once during creation
}

Python

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


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
        api_user_to_create = APIUser(
            owner=service.group,  # Current group from service context
            display_name="My Integration API Key",
            roles=[full_resource_name_from_group_name(Role.ROLE_IAM_ADMIN, service.group)],
        )

        request = CreateApiUserRequest(api_user=api_user_to_create)

        # Call the CreateApiUser method
        api_user = service.create_api_user(request)

        # Access the created API user details
        print(f"Successfully created API user: {api_user.name}")
        print(f"API key: {api_user.api_key}")  # Only available in creation response
        print(f"Display name: {api_user.display_name}")
        print(f"State: {api_user.state}")  # Initially INACTIVE
        print(f"Owner: {api_user.owner}")

        # Note: Store the API key securely - it's only returned once during creation


if __name__ == "__main__":
    main()

Java

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

import java.util.Optional;

public class CreateApiUserExample {
    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
            APIUser apiUserToCreate = APIUser.newBuilder()
                .setOwner(service.group()) // Current group from service context
                .setDisplayName("My Integration API Key")
                .addRoles(RoleUtils.fullResourceNameFromGroupName(Role.ROLE_IAM_ADMIN, service.group()))
                .build();
            
            CreateApiUserRequest request = CreateApiUserRequest.newBuilder()
                .setApiUser(apiUserToCreate)
                .build();

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

            // Access the created API user details
            System.out.println("Successfully created API user: " + apiUser.getName());
            System.out.println("API key: " + apiUser.getApiKey()); // Only available in creation response
            System.out.println("Display name: " + apiUser.getDisplayName());
            System.out.println("State: " + apiUser.getState()); // Initially INACTIVE
            System.out.println("Owner: " + apiUser.getOwner());
            
            // Note: Store the API key securely - it's only returned once during creation
        } catch (Exception e) {
            System.err.println("CreateApiUser 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