Companies House identity service: Request user authorisation code

Request authentication credentials for a web application user.

This operation is the first step in server-side web application authentication.

This operation takes the user through a web authentication journey resulting in an authorisation code being returned to the server-side web application. The web application then performs a second step of exchanging this authorisation code for an access token.

Request

GET https://identity.company-information.service.gov.uk/oauth2/authorise

Query parameters

Parameter name	Value	Description	Additional
response_type	string	Requests the type of response the authorisation API should return. For server-side web applications, this would be `code`, for JavaScript applications this would be `token`. Possible values are: `code` `token`	Required
client_id	string	Identifies the client that is making the request. This is the requestors client ID.	Required
redirect_uri	string	One of the redirect URIs registered at the time of obtaining a `client_id` and `client_secret`. Must be the same as sent during the authorisation request that returned the code.	Required
scope	string	Indicates the service access your application is requesting, the user will be asked to give their consent of these permissions to be given to your application. Scope is given as a space delimited set of permissions requested by the application.
state	string	This parameter contains any state which your application may want returned in the response roundtrip. The value should contain a nonce that your application can check to prevent cross-site-request-forgery attempts.	Required
reauthenticate	boolean	This parameter is used to force the user to reauthenticate for the application. This may be required to protect some user resources owned by the application.
hint	string	This parameter is used to supply an email address to the authentication service. The value is used to pre-populate the email address web-screen field.

Authorisation

This request requires the use of one of following authorisation methods: OAuth2.

For OAuth 2 authorisation, the following scopes are required:

Scope	Description
https://identity.company-information.service.gov.uk/user/profile.read	User profile read permission

Response

The following HTTP status codes may be returned, optionally with a response resource.

Status code Description Resource

302

Found

The users browser may be redirected to an appropriate authorisation web-screen, but will always result in a redirection to the supplied redirect_uri with a code= query parameter containing the authorization_code or an error= parameter otherwise.

Headers returned

Name	Type	Description
Location	string	The URL to which the user must be directed.

Example

GET /oauth2/authorise?scope=https://identity.company-information.service.gov.uk/user/profile.read%20https://api.company-information.service.gov.uk/company/00000000/registered-office-address.update&redirect_uri=https://somewhere.example.com/oauthcallback&response_type=code&client_id=6ghe7938zhd821hf&state=some_application_state_string HTTP/1.1

Handling the response

The response is sent to the redirect_uri passed in the authorisation request.

The redirect_uri will be of a server page that will decode the response and issue an access token exchange on the authorisation code.

The size of the code values may vary in size and be increased in the future.

GET https://somewhere.example.com/oauthcallback&code=987124y8g5r897t1t9y8b24t967g13-wzy&state=some_application_state_string HTTP/1.1