UK Companies House Authentication: API Key Setup & Security (2026)

Authentication overview

Authentication for the UK Companies House API is an essential security measure that verifies the identity of a client attempting to access its services. This process ensures that only authorised applications can retrieve or submit company data, protecting both the integrity of the data and the privacy of UK businesses. Companies House employs a straightforward authentication model, primarily relying on API keys for client identification and access control. This method is suitable for programmatic access to public datasets and services, such as retrieving company profiles, searching for companies, or accessing filing histories.

The API key acts as a unique identifier for your application, linking your requests to your developer account. When a request is made to an API endpoint, the API key must be included in the request headers, allowing the Companies House API to validate the request's origin. This approach simplifies integration while maintaining a necessary level of security for the data consumed. Understanding the proper handling and management of these keys is crucial for maintaining the security of your applications and compliance with data protection regulations like GDPR, which Companies House adheres to.

Supported authentication methods

The UK Companies House API primarily supports API key authentication. This method involves generating a unique key from the Companies House developer portal and including it in the HTTP headers of every API request. This approach is standard for many public-facing APIs, providing a balance of security and ease of implementation for developers. The API key serves as a token that grants access to the associated account's permissions.

For specific bulk data products or services that may involve more sensitive operations or higher transaction volumes, Companies House may implement additional security layers or require specific agreements, though the core API remains API key-centric. It is important to note that the API key provides access to public data, but does not typically grant permissions for actions requiring specific company authorisation, such as filing documents on behalf of a company, which would involve separate, more stringent authentication processes outside the scope of the public API.

The following table outlines the primary authentication method:

While API keys are effective for identifying the calling application, developers should be aware of the general security considerations associated with them. Unlike OAuth 2.0, which delegates authorization without sharing user credentials, API keys directly represent the developer account's access. Best practices for API key management, such as environmental variable storage and restricted access, are therefore critical. For a broader understanding of API security principles, developers can consult resources like the OAuth 2.0 specification, even if Companies House does not directly implement it for its public API.

Getting your credentials

To obtain an API key for the UK Companies House API, you need to register for a developer account on the official Companies House developer portal. This process typically involves providing basic contact information and agreeing to the terms of service. Once registered, you will be able to generate and manage your API keys.

1. Register for a developer account: Navigate to the Companies House developer documentation portal and locate the registration link. You will need to provide your email address and create a password.
2. Access the developer dashboard: After successful registration and login, you will be directed to your personal developer dashboard.
3. Generate a new API key: Within the dashboard, there will be an option to generate a new API key. This typically involves clicking a button or following a guided process. You may be prompted to provide a name or description for your key, which helps in managing multiple keys for different applications.
4. Copy your API key: Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely, as it may only be shown once for security reasons. If you lose your key, you may need to generate a new one and revoke the old one.
5. Understand rate limits: Companies House applies rate limits to API usage to ensure fair access and system stability. Be aware of these limits as you integrate the API into your applications.

It is recommended to generate separate API keys for different applications or environments (e.g., development, staging, production) to enhance security and simplify key management. This segmentation allows for easier revocation if a key is compromised without impacting other services.

Authenticated request example

Once you have obtained your API key, you can use it to make authenticated requests to the Companies House API. The key should be included in the Authorization header of your HTTP requests, using the Basic authentication scheme. Although the scheme is named "Basic", you are not sending a username and password; instead, you send your API key as the username component, with an empty password. This is a common pattern for API key authentication using the Basic scheme.

Here’s an example of how to make an authenticated request using cURL to retrieve a company profile. Replace YOUR_API_KEY with your actual API key and 00000000 with a valid company number.

curl -u YOUR_API_KEY: \
     https://api.companieshouse.gov.uk/company/00000000

In this cURL command:

• -u YOUR_API_KEY: specifies the username and password for basic authentication. By including a colon : after your API key and leaving the password empty, cURL constructs the appropriate Authorization header.
• https://api.companieshouse.gov.uk/company/00000000 is the API endpoint for retrieving a company profile.

For Python, using the requests library, the request would look like this:

import requests

api_key = "YOUR_API_KEY"
company_number = "00000000"
url = f"https://api.companieshouse.gov.uk/company/{company_number}"

response = requests.get(url, auth=(api_key, ''))

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python example also demonstrates passing the API key as the username and an empty string as the password to the auth parameter of the requests.get method. The requests library then handles the base64 encoding and header construction automatically.

For other programming languages and SDKs supported by Companies House, such as Python SDK usage or Java SDK usage, the process will involve similar steps of setting the API key within the SDK's configuration or client object before making calls.

Security best practices

Securing your API keys is paramount to preventing unauthorized access to the UK Companies House API and protecting your application's integrity. Adhering to robust security practices minimizes the risk of key compromise and potential misuse.

1. Treat API keys as sensitive credentials: API keys grant access to your account's API permissions. They should be treated with the same level of security as passwords or private cryptographic keys.
2. Do not hardcode API keys in source code: Embedding API keys directly into your application's source code makes them discoverable and vulnerable, especially if the code is publicly accessible (e.g., in a version control system). Instead, store them in environment variables, configuration files that are not committed to version control, or secure secret management services.
3. Use environment variables for production deployments: For server-side applications, storing API keys as environment variables during deployment is a standard and secure practice. This keeps the key out of the codebase and allows for easy rotation without code changes.
4. Implement client-side key protection: If your application runs client-side (e.g., in a web browser), direct exposure of API keys is generally unavoidable if the API calls are made directly from the client. In such cases, consider using a proxy server to route API requests. The proxy server can then add the API key securely on the server-side, preventing its exposure in the client's source code or network requests. This is a common pattern for many web applications to protect sensitive credentials.
5. Restrict access to API keys: Limit who has access to your API keys within your development team. Implement role-based access control (RBAC) if your secret management system supports it.
6. Rotate API keys regularly: Periodically generating new API keys and revoking old ones reduces the window of opportunity for a compromised key to be exploited. Establish a schedule for key rotation based on your organization's security policies.
7. Monitor API usage: Regularly review your API usage logs for any unusual activity or spikes that might indicate an unauthorized use of your API key. Companies House may also provide usage statistics on your developer dashboard.
8. Implement proper error handling: Ensure your application handles API errors gracefully without exposing sensitive information (like the API key) in error messages or logs.
9. Understand API scope and permissions: While Companies House API keys typically access public data, be aware of any variations in permissions for different services. Only grant the minimum necessary permissions to each key if such granular control becomes available or applicable to specific services.
10. Stay updated with Companies House security advisories: Companies House will publish any security advisories or updates regarding API access on their developer portal. Regularly check the Companies House developer documentation for the latest recommendations.

For more general guidance on securing API keys and tokens, developers can refer to industry best practices and standards, such as those discussed by organizations like the Open Web Application Security Project (OWASP) API Security Project, which provides comprehensive information on API vulnerabilities and mitigation strategies.