The existing XML Gateway API employs a custom authentication mechanism unique to Companies House, and involves the complex MD5 hashing of passwords and transaction ID’s.
The new Companies House REST API uses standard [Basic HTTP Authorisation][1]. This makes API key authentication as simple as the following curl command:
curl -v -uYOUR_APIKEY_FOLLOWED_BY_A_COLON: https://api.companiseshouse.gov.uk/company/00002065
You may have to do a little more work in code, depending on whether your client framework directly supports basic authorisation, which is highly likely, but if not, it simply comes down to setting the HTTP Authorization: header with content Basic followed by the base64 encoding of YOUR_APIKEY_FOLLOWED_BY_A_COLON:
If your API key really was YOUR_APIKEY_FOLLOWED_BY_A_COLON, then the Authorization header would be:
Authorization: Basic WU9VUl9BUElLRVlfRk9MTE9XRURfQllfQV9DT0xPTjo=
```
Cut-n-paste this base64 string to this [online base64 decoder][2] to see the content. Note the colon at the end of the API key, this is the delimiter between the username and the password and **must** be present, even if there is no password. A common error is to omit it.
Here is a quick bit of Perl which demonstrates making an API request using Basic Authorisation. I've spelt everything out, so you can see exactly how you form an `Authorization` header if you find you have to do it yourself:
```perl
#!/usr/bin/perl
use strict;
use LWP::UserAgent;
use JSON;
use Data::Dumper;
use MIME::Base64;
my $APIKEY = 'PUT_YOUR_API_KEY_HERE';
my $resource = 'https://api.companieshouse.gov.uk/company/00002065';
# Create a standard HTTP Basic authentication
# This consists of a username:password pair, but with a blank password
my $credentials = 'Basic '. encode_base64( $APIKEY.':' );
# Create a user agent and submit the request with an Authorization header.
my $ua = LWP::UserAgent->new( ssl_opts => { verify_hostname => 0 } );
my $response = $ua->get( $resource, 'Authorization' => $credentials );
die 'Error. Http status: '.$response->code.' '.$response->message unless $response->is_success;
# Decode JSON (use decode_json, as it handles UTF-8)
my $response_data = decode_json( $response->content );
# Dump out the parsed resource so you can see it.
print Dumper $response_data;
```
I hope that explains the authentication mechanism for you. If you were after anything else, let us know.
[1]: https://en.wikipedia.org/wiki/Basic_access_authentication
[2]: https://www.base64decode.org/
