Companies House identity service: Obtain an access token

Exchange an authorization code for an access_token, or refresh an existing access_token.

Exchange an authorization code

To exchange an authorization code for an access token, send a "fetch access token" API request containing the following parameters:

POST /oauth2/token HTTP/1.1

grant_type=authorization_code&
code=authorization-code&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=application-redirect-uri

This will return an accessToken resource, including a refresh_token that can be used offline to aquire a new access_token, once the access_token has expired.

Refreshing an access token

When an access token has expired, you can generate a new token without any user involvement by sending the refresh token in a request to the "fetch access token" API:

POST /oauth2/token HTTP/1.1

grant_type=refresh_token&
refresh_token=a_refresh_token&
client_id=your-client-id&
client_secret=your-client-secret

The accessToken resource returned from a refresh request will not contain a refresh_token.

Request

POST https://identity.company-information.service.gov.uk/oauth2/token

Form parameters

Parameter name	Value	Description	Additional
client_id	string	Identifies the client that is making the request.	Required
client_secret	string	The requesters client secret that was obtained when registering the application.	Required
grant_type	string	The grant type defined by the OAuth 2.0 specification. Possible values are: `authorization_code` `refresh_token`	Required
code	string	The authorisation code returned by the authorisation API request. Required if `grant_type` is `authorization_code`.
refresh_token	string	The refresh token returned from the original authorisation code exchange. Required if `grant_type` is `refresh_token`.
redirect_uri	string	One of the redirect URIs registered at the time of obtaining a client_id and secret. Must be the same as sent during the authorisation request that returned the code. Required if `grant_type` is `authorization_code`.

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
200	OK Access token returned	accessToken
400	Bad Request Invalid request or access token

Example - Request an access token

POST /oauth2/token HTTP/1.1
Host: https://identity.company-information.service.gov.uk
Content-Type: application/x-www-form-urlencoded
Content-Length: 216

code=78hfbvkwe9823bvkjsbw99bgsdkjb923&amp;
client_id=6ghe7938zhd821hf-domain&amp;
client_secret=<client_secret>&amp;
redirect_uri=https://somewhere.example.com/oauthcallback/token&amp;
grant_type=authorization_code

HTTP/1.1 200 Found
Access-Control-Allow-Origin: *
Connection: close
Content-Type: application/json; charset=utf-8

{
    "access_token":  "12397h2giu24g2o0781y3r9181-1r9uhf19fh13f98h1f:1fiubfv81g3f",
    "expires_in" :   "3600",
    "token_type" :   "Bearer",
    "refresh_token": "vdi9uwerg0y34t-1rtouygb2frv89tgtg13g13g-1grvyb1f49o1b"
}