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/authorisation?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