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.iam.api_user.v1 import (
    APIUser,
    ApiUserService,
    CreateApiUserRequest,
)
from meshtrade.iam.role.v1 import Role, full_resource_name_from_group_name


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_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