diff --git a/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache b/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache
index 3a36ce14073..06aae8a0e55 100644
--- a/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache
@@ -118,10 +118,12 @@ sub call_api {
     $self->{ua}->timeout($self->{http_timeout} || $WWW::{{moduleName}}::Configuration::http_timeout); 
     $self->{ua}->agent($self->{http_user_agent} || $WWW::{{moduleName}}::Configuration::http_user_agent);
     
+    $log->debugf("REQUEST: %s", $_request->as_string);
     my $_response = $self->{ua}->request($_request);
+    $log->debugf("RESPONSE: %s", $_response->as_string);
   
     unless ($_response->is_success) {
-        croak("API Exception(".$_response->code."): ".$_response->message);
+        croak(sprintf "API Exception(%s): %s\n%s", $_response->code, $_response->message, $_response->content);
     }
        
     return $_response->content;
@@ -294,13 +296,23 @@ sub get_api_key_with_prefix
     }
 }
 
-# update hearder and query param based on authentication setting
+# update header and query param based on authentication setting
 #  
 # @param array $headerParams header parameters (by ref)
 # @param array $queryParams query parameters (by ref)
 # @param array $authSettings array of authentication scheme (e.g ['api_key'])
 sub update_params_for_auth {
     my ($self, $header_params, $query_params, $auth_settings) = @_;
+    
+    # we can defer to the application
+    if ($self->{auth_setup_handler} && ref($self->{auth_setup_handler}) eq 'CODE') {
+    	$self->{auth_setup_handler}->(	api_client => $self,
+    									header_params => $header_params,
+    									query_params => $query_params,
+    									auth_settings => $auth_settings, # presumably this won't be defined if we're doing it this way
+    									);
+    	return;
+    }
   
     return if (!defined($auth_settings) || scalar(@$auth_settings) == 0);
   
diff --git a/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache b/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache
index 2ea2db72402..fc309c91b9c 100644
--- a/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache
@@ -45,19 +45,54 @@ my %_apis = map { $_ =~ /^WWW::{{moduleName}}::(.*)$/; $1 => $_ }
 			grep {$_ =~ /Api$/} 
 			usesub 'WWW::{{moduleName}}';
 
+=head1 new()
+	
+	All parameters are optional, and are passed to and stored on the api_client object. 
+	
+	base_url: supply this to change the default base URL taken from the Swagger definition.
+	
+	auth_setup_handler: a coderef you can supply to set up authentication.
+	
+		The coderef receives a hashref with keys: api_client, query_params, header_params, auth_settings.
+		
+		my $api_factory = WWW::{{moduleName}}::ApiFactory->new( auth_setup_handler => \&setup_auth );					  								);
+	
+		sub setup_auth {
+			my %p = @_;
+			$p{header_params}->{'X-SomeApp-FunkyKeyName'} = 'aaaaabbbbbcccccddddd';
+		}
+		
+=cut	
+
 sub new {
     my ($class, %p) = (shift, @_);
 	$p{api_client} = WWW::{{moduleName}}::ApiClient->new(%p);			
 	return bless \%p, $class;
 }
 
+=head1 get_api($which)
+
+	Returns an API object of the requested type. 
+	
+	$which is a nickname for the class: 
+	
+		WWW::FooBarClient::BazApi has nickname 'Baz'
+		
+=cut
+
 sub get_api {
 	my ($self, $which) = @_;
 	croak "API not specified" unless $which;
 	my $api_class = $_apis{"${which}Api"} || croak "No known API for '$which'";
-	return $api_class->new(api_client => $self->_api_client); 
+	return $api_class->new(api_client => $self->api_client); 
 }
 
-sub _api_client { $_[0]->{api_client} }
+=head1 api_client()
+
+	Returns the api_client object, should you ever need it.
+	
+=cut
+
+sub api_client { $_[0]->{api_client} }
 
 1;
diff --git a/modules/swagger-codegen/src/main/resources/perl/api.mustache b/modules/swagger-codegen/src/main/resources/perl/api.mustache
index e69e4e3066f..d305d69b7fa 100644
--- a/modules/swagger-codegen/src/main/resources/perl/api.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/api.mustache
@@ -100,7 +100,7 @@ sub {{nickname}} {
     {{#formParams}}# form params
     if ( exists $args{'{{paramName}}'} ) {
         {{#isFile}}$form_params->{'{{baseName}}'} = [] unless defined $form_params->{'{{baseName}}'};
-        push $form_params->{'{{baseName}}'}, $args{'{{paramName}}'};
+        push @{$form_params->{'{{baseName}}'}}, $args{'{{paramName}}'};
         {{/isFile}}
         {{^isFile}}$form_params->{'{{baseName}}'} = $self->{api_client}->to_form_value($args{'{{paramName}}'});
         {{/isFile}}
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm
index f75bf24e031..de4a3e2d2fb 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm
@@ -118,10 +118,12 @@ sub call_api {
     $self->{ua}->timeout($self->{http_timeout} || $WWW::SwaggerClient::Configuration::http_timeout); 
     $self->{ua}->agent($self->{http_user_agent} || $WWW::SwaggerClient::Configuration::http_user_agent);
     
+    $log->debugf("REQUEST: %s", $_request->as_string);
     my $_response = $self->{ua}->request($_request);
+    $log->debugf("RESPONSE: %s", $_response->as_string);
   
     unless ($_response->is_success) {
-        croak("API Exception(".$_response->code."): ".$_response->message);
+        croak(sprintf "API Exception(%s): %s\n%s", $_response->code, $_response->message, $_response->content);
     }
        
     return $_response->content;
@@ -294,13 +296,23 @@ sub get_api_key_with_prefix
     }
 }
 
-# update hearder and query param based on authentication setting
+# update header and query param based on authentication setting
 #  
 # @param array $headerParams header parameters (by ref)
 # @param array $queryParams query parameters (by ref)
 # @param array $authSettings array of authentication scheme (e.g ['api_key'])
 sub update_params_for_auth {
     my ($self, $header_params, $query_params, $auth_settings) = @_;
+    
+    # we can defer to the application
+    if ($self->{auth_setup_handler} && ref($self->{auth_setup_handler}) eq 'CODE') {
+    	$self->{auth_setup_handler}->(	api_client => $self,
+    									header_params => $header_params,
+    									query_params => $query_params,
+    									auth_settings => $auth_settings, # presumably this won't be defined if we're doing it this way
+    									);
+    	return;
+    }
   
     return if (!defined($auth_settings) || scalar(@$auth_settings) == 0);
   
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm
index 811031b06a3..701a22603c5 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm
@@ -45,19 +45,54 @@ my %_apis = map { $_ =~ /^WWW::SwaggerClient::(.*)$/; $1 => $_ }
 			grep {$_ =~ /Api$/} 
 			usesub 'WWW::SwaggerClient';
 
+=head1 new()
+	
+	All parameters are optional, and are passed to and stored on the api_client object. 
+	
+	base_url: supply this to change the default base URL taken from the Swagger definition.
+	
+	auth_setup_handler: a coderef you can supply to set up authentication.
+	
+		The coderef receives a hashref with keys: api_client, query_params, header_params, auth_settings.
+		
+		my $api_factory = WWW::SwaggerClient::ApiFactory->new( auth_setup_handler => \&setup_auth );					  								);
+	
+		sub setup_auth {
+			my %p = @_;
+			$p{header_params}->{'X-SomeApp-FunkyKeyName'} = 'aaaaabbbbbcccccddddd';
+		}
+		
+=cut	
+
 sub new {
     my ($class, %p) = (shift, @_);
 	$p{api_client} = WWW::SwaggerClient::ApiClient->new(%p);			
 	return bless \%p, $class;
 }
 
+=head1 get_api($which)
+
+	Returns an API object of the requested type. 
+	
+	$which is a nickname for the class: 
+	
+		WWW::FooBarClient::BazApi has nickname 'Baz'
+		
+=cut
+
 sub get_api {
 	my ($self, $which) = @_;
 	croak "API not specified" unless $which;
 	my $api_class = $_apis{"${which}Api"} || croak "No known API for '$which'";
-	return $api_class->new(api_client => $self->_api_client); 
+	return $api_class->new(api_client => $self->api_client); 
 }
 
-sub _api_client { $_[0]->{api_client} }
+=head1 api_client()
+
+	Returns the api_client object, should you ever need it.
+	
+=cut
+
+sub api_client { $_[0]->{api_client} }
 
 1;
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
index c8f0fc98ff3..a7cb9a973df 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
@@ -515,7 +515,7 @@ sub upload_file {
     }# form params
     if ( exists $args{'file'} ) {
         $form_params->{'file'} = [] unless defined $form_params->{'file'};
-        push $form_params->{'file'}, $args{'file'};
+        push @{$form_params->{'file'}}, $args{'file'};
         
         
     }