Interaction with some Companies House API functionality requires oauth2 authorisation. In web server apps, interaction with the Companies House API requires end-user involvement for authentication to prove their identity before the API will allow access.
In a web server process flow, there must be end user involvement and the process flow is as follows:
Applicationwith the Companies House Developer Hub.
client_secretwhich must be stored securely by the developer.
client_secretcombination for interactions with the Companies House OAuth 2.0 service.
/oauth2/authoriseendpoint with the developers
client_idand other details including the requested scope(s) and a registered
Applicationto perform certain actions on their behalf.
redirect_uriprovided with a
codeparameter to be used in the next stage.
codeto exchange for the users
refresh_tokenby making a
POSTrequest to the
code, the developers
client_secretand some other relevant information. The
grant_typemust be set to
authorization_codeto exchange an authorization code for an access token.
/oauth2/tokenendpoint again to exchange the refresh token for a new access token. The
grant_typemust be set to
refresh_tokento exchange an refresh token for an access token.
Scopes are defined against API specs where they are required e.g. manipulate company data API specs for transactions and registered office address APIs. Where scopes are defined in API specs like these basic authorization (API keys) will not be allowed as scopes are only applicable when using OAuth2 bearer authorization.
Scopes map to permissions against API resources using the full domain to the live resource with specific permissions appended to the end after a period. The domain is always the live version even when testing in the sandbox environment e.g.
https://identity.company-information.service.gov.uk/user/profile.read should be used for permission to read the user profile whether you're integrating with the live or sandbox environment.
When your software redirecte users to sign in with Companies House they will be shown a permission grant screen which will ask them to grant access for your software to perform specific actions. These actions will be mapped from the requested scopes e.g.
https://identity.company-information.service.gov.uk/user/profile.read will ask for permission to read their user profile (i.e. email address).
Each endpoint is documented with examples within thie developer site.
Companies House have also written an example Third Party Test Harness application that shows how a web server application can interact with the Companies House OAuth 2.0 service. The README of this GitHub repository details how to configure and run the test harness.