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&
client_id=6ghe7938zhd821hf-domain&
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"
}