To be able to explore and use the the Companies House streaming API, you need
to register a user
account with Companies House.
Visit the Your Applications
page of the Companies House Developer Hub. This will show you the REST API and
streaming API applications you have already registered, and allow you to
register further applications.
Applications that are to use the streaming API must be registered as such, the
REST API and streaming API keys are not interchangable.
To register a new application, click the Register an application button.
You will now be asked which type of application you are registering, choose
Streaming API.
Fill in your Application name, giving it a meaninful description and,
if appropriate, a list of Restricted IPs and when you're done, click Register.
The hub will register your application, and provide you with a unique
streaming API key that you will use to authenticate your application every
time you connect to a streaming API.
When connecting to the streaming API, you authenticate using Basic
authentication, which is wildly supported by HTTP client libraries and command
line tools.
To authorise using Basic authentication, the client sends the server an
Authorization HTTP header
specifying a scheme type of Basic and a value that is constructed as follows:
- An ASCII colon '
:' is appended to the end of the streaming API key
- Basic-credentials are created by encoding this concatenated sequence by
using Base64 RFC4648
into a sequence of US-ASCII characters RFC4648.
Given an example streaming API key of a-streaming-api-key, the complete
HTTP authorization header would be:
Authorization: Basic YS1zdHJlYW1pbmctYXBpLWtleTo==
Note that you will get a different and invalid base64 encoded value if you
ommit the colon ':' from the end of the API key before encoding.
The following curl request authenticates with Basic authentication:
curl -v -u a-streaming-api-key: "https://stream.companieshouse.gov.uk/companies?timepoint=187124872486"